Eggplant Web Performance Analyzer API Formats

The Eggplant Web Performance Analyzer API uses specific formatting in its request responses, and it requires you to use specific formatting for certain parameters in those requests.

On this page:

Dates

All date and times use the ISO8601 format. This includes any returned data, as well as any queries that allow you to filter on date and time. This formatting ensures that all dates and times can be used between responses and requests, as well as being in a standard format that is well supported across different programming languages, and is human readable.

The ISO standard makes the timezone/offset mandatory, which ensures that there is no ambiguity as to which date or time is being used (i.e., 2016-04-07T08:06:47+00:00).

All dates returned by the API are in Greenwich mean time (GMT), so a zero offset from Coordinated Universay Time (UTC) returns as 2016-04-07T08:06:47+00:00

The Eggplant Web Performance Analyzer web portal shifts between GMT and British Summer Time (BST) as shown in the footer:

Eggplant Web Performance Analyzer footer, indicating daylight saving time

Duration Metrics

To ensure consistency, all durations are specified in seconds when using the API. There are some values that are specified differently in the portal (for human readability), but these are defined in seconds, to ensure consistency within the API.

For example, the following values are specified in seconds in the API, but in milliseconds in the portal:

Item Metric in Portal Metric in API

Inactivity timeout

Milliseconds, e.g., 500 Seconds, e.g., 0.5
Latency Milliseconds, e.g., 200 Seconds, e.g., 0.2
Crawl timeout Minutes, e.g., 180 Seconds, e.g., 10800

URL Encoding Parameters

All parameter values that are sent to the API in query strings need to be URL encoded. Query strings are typically used to filter the query, for example to limit the search to a particular date/time period or to get something from the API that relates one thing to another.

More details can be found in each section below, but if we take an example of searching for all objects (network requests) that have been made within a test run, we are searching for objects for a given testRun, as follows:

Path /objects?testRun={sref_of_test_run}

The testRun and sref_of_test_run are query strings sent as parameters to the /objects endpoint. An example sref_of_test_run could be testRuns/12345. Only the value of the query string is encoded:

Path /objects?testRun=testRuns/12345

Doing this, we end up making the following request:

Path /objects?testRun=testRuns%2F12345
Important: Date and time parameters in your query must be encoded. You cannot issue a query like this: /testRuns?fromDate=2016-07-01T00:00:00+00:00&toDate=2016-07-31T23:59:59+00:00

Encoding the date and time parameter values results in the following query:

Path /testRuns?fromDate=2016-07-01T00%3A00%3A00%2B00%3A00&toDate=2016-07-31T23%3A59%3A59%2B00%3A00

Remember it is only the query parameter values that are encoded, which is why the &toDate= in the above example is not encoded, whereas the value 2016-07-31T23:59:59+00:00 is encoded.

Most programming languages include methods for URL encoding the parameters for you, such as urlencode (PHP), UrlEncode (C#), URLEncoder.encode (Java) and encodeURI (JavaScript).

Pagination

By default, most endpoints will return a limited number of records in the response. This can be increased to a maximum of 1,000. If not specified, the default page size is up to 25 records.

The following parameters are used to control the pagination:

  • paginationPageSize: The maximum number of records to return
  • paginationPage: Which page to return (indexed from 1)

The following examples show how pagination is used with the /jobs endpoint, but the principle is the same for other endpoints:

Request Parameters Behavior
/jobs Get the latest jobs using the default page size
/jobs?paginationPageSize=500 Get the latest 500 jobs in the account
/jobs?paginationPage=3 Get the latest jobs from the third page using the default page size
/jobs?paginationPageSize=500&paginationPage=3 Get the latest set of 500 jobs from the third page of 500
/jobs?paginationPageSize=5000 HTTP/400 Bad Request
(1,000 is the maximum number of jobs that can be returned with each request)

All requests to the API include a meta section in the response, which contains more information about the data being returned. One of the parameters returned is paginationTotalResults, which describes how many records match the request.

For example, if your response includes the following, then you know there are 7,724 records you can retrieve, up to 1,000 records at a time:

Body

"meta": {

"paginationTotalResults": 7724,

"response_in_sec": 0.13

},

 

This topic was last updated on October 11, 2019, at 11:18:53 AM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2019 Eggplant