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.
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:
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 |
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 }, |