APM API

The APM API makes data collected and generated by AppNeta Performance Manager (APM) available for analysis, reporting, and presentation in third-party systems. Results are delivered in a lightweight JSON format that can be readily consumed by a broad range of clients. As well as collecting system data, the API also provides the ability to configure and control APM.

In addition to the APM API, there is an API for administering Enterprise Monitoring Points (EMPs) - the Admin API. For information on accessing the Admin API see Admin API.

Getting started with the APM API

The best place to start learning and experimenting with the API is through the interactive API interface. It provides a good place to stage API calls before implementing them in your integration software. In addition to allowing you to experiment with the API, the interactive interface provides detailed documentation about each endpoint and its parameters.

As an example, to access the APM API interface and obtain a simple response from APM:

1. Log in to APM.
2. If you have more than one organization, change the organization to the one you are interested in.
3. Navigate to > API.
   • The interactive APM API interface appears.
4. Navigate to path > GET /v3/path.
5. Click Try it out!.
   • The Curl field shows the curl command string (except for the authentication information) that can be used from the command line to produce the same result. See Using curl for more information
   • The Request URL field shows the URL the request was made to.
   • The Response Body field shows the JSON formatted response sent by APM. In this case, all network paths within the selected organization.
   • The Response Code is the response code sent by APM. Successful responses have a “2xx” code. See Error codes for a list of error codes and their meaning.
   • The Response Headers is the header information sent by APM.

You can experiment by filling in a few parameters (to filter the results) and clicking Try it out!. You can also experiment with other endpoints.

Authentication

The APM API supports Basic authentication. This requires an APM username and password be passed as part of the API request - either explicitly in plain text (not recommended) or encoded with Base64 (recommended). See Using curl to see how this is achieved with curl. See the 401 codes in Error codes for the error codes associated with authentication issues.

Using curl

One of the outputs from the interactive API interface is a curl command that can be used to generate the same result as is in the Response Body, but from the command line. One caveat is that the command parameters provided do not include authentication information. For example, the curl command returned by GET /v3/path is:

   curl -X GET --header "Accept: application/json" "https://<your_APM_node>.pm-st.appneta.com/api/v3/path?api_key=v3&api_key=v3"

<your_APM_node> - the name of the APM node you are using.

Using the command directly would fail as there are no credentials included in the list of parameters.

Including basic authentication information

The simplest way to include authentication information in the curl command is with the -u parameter. For example:

   -u <email_address>:<password>

<email_address> - the email address you use to access APM.
<password> - the password you use to access APM.

The updated command looks as follows:

   curl -X GET --header "Accept: application/json" -u <email_address>:<password> "https://<your_APM_node>.pm-st.appneta.com/api/v3/path?api_key=v3&api_key=v3"

If you leave off “:<password>”, you will be prompted for your password.

Including encoded authentication information

The downside of using the -u parameter is that your credentials are shown in plain text. A better way to include authentication information is to use the base64 command to encode your credentials and then include them using the -H parameter. Using this method does not expose your user credentials.

To encode your credentials use:

   echo -n <email_address>:<password> | base64

A string of characters is returned. For example:

   a21hbqFwdeuZ2rzzYWd2YWsjrWeAYXdBwbmzV0YS5j9gRmsQmtkjxMT4Fy9j

Use the -H parameter (instead of -u) to include this information. For example:

   -H "Authorization: Basic a21hbqFwdeuZ2rzzYWd2YWsjrWeAYXdBwbmzV0YS5j9gRmsQmtkjxMT4Fy9j"

The updated command looks as follows:

   curl -X GET --header "Accept: application/json" -H "Authorization: Basic a21hbqFwdeuZ2rzzYWd2YWsjrWeAYXdBwbmzV0YS5j9gRmsQmtkjxMT4Fy9j" "https://<your_APM_node>.pm-st.appneta.com/api/v3/path?api_key=v3&api_key=v3"

This command provides output but it is unformatted and difficult to read.

Making the output easier to read

To make the curl output more intelligible, use | python -m json.tool after each curl command. For example:

   curl -X GET --header "Accept: application/json" -H "Authorization: Basic a21hbqFwdeuZ2rzzYWd2YWsjrWeAYXdBwbmzV0YS5j9gRmsQmtkjxMT4Fy9j" "https://<your_APM_node>.pm-st.appneta.com/api/v3/path?api_key=v3&api_key=v3" | python -m json.tool

The output from this command is properly formatted.

Obtaining “IDs”

A number of endpoints (for example, GET /v3/path/{id}/data) require an “id” parameter, to filter a result set (for example, “Path ID” or “Web Path ID”). The easiest way to obtain specific IDs is to navigate to a page in the APM user interface showing details of that object. For example, in APM, if you navigate to Delivery > Network Paths and hover over a path name, the “pathid” of the network path is shown at the bottom left of the page. Similarly, if you navigate to Experience > Web Paths and hover over a web path name, the “webpathid” of the web path is shown at the bottom left of the page.

Obtaining a timestamp in Unix time

There are endpoints (for example, GET /v3/path/{id}/data) that require a timestamp in “Unix time” (the number of seconds elapsed since midnight (UTC) on January 1, 1970). The simplest way to obtain Unix time is with a free online tool like the Unix timestamp tool.

Rate limit

AppNeta limits the number of API requests that can be made over a given period of time. Currently the rate limit is 50 requests every 10 seconds.

Error codes

The error codes returned by APM include:

• 400 - Bad Request
  • Indicates that the parameters sent with the request were incorrect.
• 401 - Full authentication is required to access this resource
  • This indicates that no credentials were passed with the request.
• 401 - Bad credentials
  • This indicates that credentials were passed correctly with the request but were invalid. Try using different credentials.
• 401 - Failed to decode basic authentication token
  • This indicates that an encoded token could not be decoded. Try recreating the token.
• 403 - Access is denied
  • This indicates that the server understood the request but will not fulfill it. It is likely that you do not have permissions to access the resource you were trying to access. For example, this can occur if you are trying to access the wrong organization.
• 404 - Not found
  • This indicates that the specified API endpoint was invalid. Check the specified URL string.
• 406 - Not Acceptable
  • This indicates, for example, incorrect information in the request header. Review the request.
• 500 - Internal server error
  • This indicates that there is an issue on the system you are targeting. Try the request again later.