Using Eggplant Monitoring API Queries
After you build a query in Eggplant Monitoring, you can run it manually or incorporate it into an application.
Running Queries Manually
Follow these steps to manually run your query:
- Log into the API user interface to generate a new API key.
- Replace the existing API key in your query with the new key.
- Change any other variable elements of the query (such as dates) as required.
- Resubmit the revised query URL via your browser.
Running Queries in Applications
The majority of API usage is via purpose-built applications. There are several important things to account for when building such applications:
- Generating a New API Key
- Handling Error Messages
- Specifying the Response Format
- Considering Data Presentation
Handle Generating a New API Key
If the interval between your queries exceeds 59 minutes, the application must generate a new API key for each use. However, even if this is not the case, it's recommended that you incorporate functionality to create a new key automatically if the response indicates an authentication failure (see next section for details about error messages). To generate a new key programmatically, you append the appropriate username and password to the API URL as shown below and submit this request (substituting the values highlighted in red appropriately):
https://api.mon.eggplant.cloud/current/username/me@my.com/password/mypassword
This generates a response that includes the new API key (highlighted below in green):
<SiteConfidenceApi Version="current">
<Request/>
<Response Status="Ok" Code="200" Message="Success.">
<ApiKey Lifetime="3600">abcdefghijklmnopqrstuvwxyz123456</ApiKey>
</Response>
</SiteConfidenceApi>
Handle Error Messages
Errors should be handled in way that notifies interested parties of the problem in a timely manner, with a clear and meaningful explanation of the problem where possible. Each query made to the API results in a response that clearly defines if it was successful or not. The <Response> element (or its equivalent for non-XML formats) contains this information, and if the query was successful this element appears as follows:
<SiteConfidenceApi Version="current">
<Request/>
<Response Status="Ok" Code="200" Message="Success.">
</Response>
</SiteConfidenceApi>
Should the query fail for some reason, the API will report an error. Certain failures might arise due to a programmatic error with the query.
| Code | Message | Meaning | Solution |
|---|---|---|---|
| 101 (HTTP) | Service currently unavailable | The API is down or unreachable | Contact support |
| 301 (response) | Maximum number of items exceeded. Response was truncated. | You requested too much data for the API to provide in one query | Narrow your query, or divide it into several queries |
| 401 (response) | Authentication failure | The API key expired OR The application provided an incorrect API key OR The account you are using does not have access to the API | Generate a new key and use it in your query OR Enter a different key in the query OR Contact your account manager |
| 402 (response) | You have exceeded the maximum number of allowed requests. | The number of API queries made by your company has exceeded the contractual allowance | Contact support or your account manager |
| 402 (HTTP) | Payment required | The number of API queries made by your company has exceeded the contractual allowance | Contact support or your account manager |
| 403 (HTTP) | Not Found | The API cannot resolve the supplied query URL | Most likely the URL is constructed incorrectly, i.e., with an API key with a length other than 32 characters |
This table is also included in the Eggplant Monitoring API Troubleshooting Guide.
Specify the Response Format
The API allows you to specify certain formats for the returned data. You can choose from XML, JSON, PHP, or YAML. The default is XML, but if you require the response to be in one of the other formats, append /Format/format to your query, replacing format with the name of the format you need. For example, to format the response as JSON, submit a query of the form:
https://api.mon.eggplant.cloud/current/.../Format/json
Consider Data Presentation
Most customers further filter the data from the API according to their specific business needs, then pass it to some type of off-the-shelf real-time reporting software. Exporting the filtered data to a spreadsheet can be sufficient, as well. Rarely is there the need to build a bespoke presentation layer.