Skip to main content

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:

  1. Log into the API user interface to generate a new API key.
  2. Replace the existing API key in your query with the new key.
  3. Change any other variable elements of the query (such as dates) as required.
  4. 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:

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.

CodeMessageMeaningSolution
101 (HTTP)Service currently unavailableThe API is down or unreachableContact support
301 (response)Maximum number of items exceeded. Response was truncated.You requested too much data for the API to provide in one queryNarrow your query, or divide it into several queries
401 (response)Authentication failureThe 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 allowanceContact support or your account manager
402 (HTTP)Payment requiredThe number of API queries made by your company has exceeded the contractual allowanceContact support or your account manager
403 (HTTP)Not FoundThe API cannot resolve the supplied query URLMost 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.