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 APM API is through its interactive 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 interactive APM API interface and obtain a simple response from APM:
- Log in to APM.
- If you have more than one organization, change the organization to the one you are interested in.
- Navigate to > Explore API.
- The interactive APM API interface appears.
- Navigate to path > GET /v3/path.
- 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. Care should be taken with PUT, POST, and DELETE requests as they affect your live data.
API version
When using the interactive APM API interface you will typically use the current API version (for example, V3). At times, new or changed endpoints will become available for early access prior to being promoted to the latest API version. These will be in a BETA version of the API.
To select the APM API version in the interactive APM API interface:
- Log in to APM.
- If you have more than one organization, change the organization to the one you are interested in.
- Navigate to > API.
- The interactive APM API interface appears.
- At the top of the page, use the version dropdown to select the API version.
- All interactions in the interactive interface will use the selected version.
Authentication
The APM API supports Access Token authentication (recommended) and Basic authentication. Access Token authentication requires an access token that you create on APM. Basic authentication requires an APM username and password. In either case the authentication information is passed as part of the API request.
See Using curl to see how authentication 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 APM API interface is a curl command that can be used to generate the same result that appears 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 -H "Accept: application/json" "https://<your_APM_node>.pm.appneta.com/api/v3/path"
<your_APM_node> - the name of the APM node you are using.
Using the command directly will fail as there are no credentials included in the list of parameters.
Including access token authentication information
Using access tokens is the recommended way to authenticate in the APM API. Prior to using an access token you must create it in APM. You can then use it in the API request header. For example:
-H "Authorization: Token <token>"
<token> - the access token you created to access APM.
The updated command line looks as follows:
curl -X GET -H "Authorization: Token <token>" -H "Accept: application/json" "https://<your_APM_node>.pm.appneta.com/api/v3/path"
Including basic authentication information
Basic authentication can also be used to access the API. With curl, this information is passed via 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 line looks as follows:
curl -X GET -u <email_address>:<password> -H "Accept: application/json" "https://<your_APM_node>.pm.appneta.com/api/v3/path"
If you leave off “:<password>”, you will be prompted for your password.
Making the output easier to read
To this point, the curl examples provide output but it is unformatted and difficult to read. To make the curl output more intelligible, use | python3 -m json.tool
after each curl command. For example:
curl -X GET -H "Accept: application/json" "https://<your_APM_node>.pm.appneta.com/api/v3/path" -u <email_address>:<password> | python3 -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.
Retrieving bulk data
There are three endpoints that can return potentially very large amounts of data: GET /v3/path/data, GET /v3/webPath/data, and GET /v3/dns/webPath/data. To limit the amount of data returned, a size restriction is in place. A single request can return a maximum of 20 path-days of data. For example:
- 20 days of data for 1 path
- 10 days of data for 2 paths
- 1 day of data for 20 paths
- 0.5 days of data for 40 paths
- 1 hour of data for 480 paths
- 15 minutes of data for 1,920 paths
For these endpoints, use the limit parameter to limit the number of paths returned, the from and to parameters to specify the time range, and the page parameter to specify the page of data to retrieve.
For example, to retrieve a day of data for 100 paths in five 20 path chunks, you would set:
- limit = 20
- from = start of day in UNIX time
- to = end of day in UNIX time
- page = 1 to 5 (i.e. make five requests with a different page number in each request)
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.
Sample code
As mentioned in previous sections, you can access the APM API using its interactive interface or by using the curl command. But, because it is a RESTful API, there are many ways to interact with the APM API programmatically. Virtually any modern programming language can be used. For our examples, we use Python.
Note: As you work through the examples below, use the interactive APM API interface to view documentation for each of the API endpoints. This information can be used to determine how to construct the request string and to understand what the response objects are expected to look like.
Loading code samples
Sample Python code files are available in a repository on GitHub. To use these files:
- Install git if it is not already installed on your computer.
- Sign up for a GitHub account if you don’t already have one.
- Clone the repository to your local system (e.g.
git clone https://github.com/appneta/docs-apm-api-sample-code.git
).- A local directory is created.
- Update the credentials.py file with your APM server name (e.g. app-01.pm.appneta.com) and APM API credentials (access token).
- Download and install Python.
- Run the sample programs and view the code files to see what they do and how they do it:
- The “app-…” files (e.g.
python3 app-organizations.py
) retrieve a variety of APM system data. - The “path-…” files create/delete/show network paths identified in the paths.csv file.
- Update paths.csv with valid information then run any of the “path-…” files (e.g.
python3 path-create.py
) to see what they do.
- Update paths.csv with valid information then run any of the “path-…” files (e.g.
- “aggregation-test.py” is used to show how data is aggregated over time.
- Functions used in the program files are defined in api_fns.py.
- The “app-…” files (e.g.
- Modify any of these files or create your own code to use the APM API.
The sample files and the purpose of each are as follows:
Filename | Description |
---|---|
credentials.py | User credentials and server name |
api_fns.py | Functions to access the APM API |
app-appliances.py | Prints Monitoring Point info |
app-mp-status.py | Prints Monitoring Point status |
app-network-path-info.py | Prints network path info |
app-network-path-stats.py | Prints network path stats |
app-network-path-status.py | Prints network path status |
app-network-path-status-group.py | Prints network path status by group |
app-network-path-status-saved-list.py | Prints network path status by saved list |
app-organizations.py | Prints organization info |
app-web-path-info.py | Prints web path info |
app-web-path-stats-group.py | Prints web path stats info by group |
app-web-path-stats.py | Prints web path stats info |
app-web-path-status-org.py | Prints web path status by organization |
app-web-path-status.py | Prints web path status |
paths.csv | List of paths to create/delete/show |
path-create.py | Create paths in “paths.csv” file |
path-delete.py | Delete paths in “paths.csv” file |
path-show.py | Show paths in “paths.csv” file |
aggregation-test.py | Shows how data is aggregated |
API access function with no parameters
An API access function is one that interacts with an APM API endpoint. All of the sample programs use at least one of the API access functions located in api_fns.py. In this section we review a simple API access function (get_org()
) that accesses the GET /v3/organization endpoint, which requires no parameters.
Within api_fns.py you’ll find the get_org()
code. It looks as follows:
1 2 3 |
|
The function simply creates a request string (url) to access the GET /v3/organization endpoint.
- apm_server - (defined in credentials.py) is the APM server you use.
- access-token - (defined in credentials.py) is a valid API access token on your APM server.
requests.get()
makes the GET request to the endpoint specified in the url using the access-token for authentication. All the sample API access functions defined in api_fns.py use the Python Requests library to access the API.
API access function with path parameters
In the previous section we looked at the get_org()
function. This function required no parameters as the GET /v3/organization endpoint it accesses requires no parameters. In this section we look at GET /v3/webApplication/{web_app_grp_id}/monitor. This is an endpoint that requires a “path parameter” - a parameter (in this case the web app group ID: {web_app_grp_id}
) included in the URL path. Path parameters are not optional. This endpoint is accessed using the get_web_path()
function. Within api_fns.py you’ll find the get_web_path()
code. It looks as follows:
1 2 3 4 |
|
As with get_org()
, a request string (url) is created then the GET request is sent via requests.get()
. In this case, the URL path contains the web app group ID as required by the endpoint.
API access function with query parameters
A query parameter is one that appears after the “?” in the endpoint URL. Query parameters are typically optional.
In this section we look at the GET /v3/path endpoint. It can take an optional organization ID parameter. If an organization ID is specified, the endpoint returns network path information for all network paths in the organization. Without the parameter it returns network path information for all paths in all organizations. Within api_fns.py you’ll find the get_network_path()
code. It looks as follows:
1 2 3 4 5 |
|
As with the other functions we’ve looked at so far, a request string (url) is created then the GET request is sent via requests.get()
. In this case, the org_id parameter is optional and defaults to None. If org_id is passed, it is included as a query parameter in the url string.
API access function with body parameters
In the previous examples we have reviewed endpoints (and the functions that call them) that use path parameters and query parameters. Another way that parameters are passed are in an object within the body of the request. The POST /v3/path endpoint is an example of this. Within api_fns.py you’ll find the create_network_path()
code. It looks as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
In this case the url is very basic and the parameters are included as part of the body object. The headers object specifies the type of content being passed - in this case a JSON object. Also note that because the endpoint uses the POST command, this function uses requests.post()
rather than requests.get()
.
Using the API access functions
You will notice that one of the things all the sample API access functions have in common is that they return the result of one of the requests functions (for example requests.get()
). These return an object containing a variety of information including a status code (the HTTP response status) and the JSON response body. All sample programs that call an API access function check for a valid response before continuing. For example, within app-organizations.py you’ll see the following:
1 2 3 4 5 6 7 8 9 10 |
|
get_org()
is called and returns a response: r. If the response status (r.status_code) is okay, information about each organization returned is printed, otherwise an error is printed. If you want to see all the organization information returned, uncomment # pp_json(organization)
.
As another example, within app-mp-status.py you’ll see the following:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
This is similar to the first example in that get_org()
is called, but for each organization get_appliance()
is called using the organization information (organization['id']
) retrieved. From this, a list of Monitoring Points and their connection status is printed. All the “app-…” program files are similar.
Bulk operations
One of the primary uses of the APM API is to facilitate bulk operations in cases where performing an operation from the Web Admin interface or the interactive APM API interface is impractical. For example, if you need to create hundreds or thousands of network paths, you’ll want to automate this task. paths-create.py is a sample program that creates network paths given a list of organization IDs, Monitoring Point names, targets, and target locations listed in paths.csv. The code looks as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
It simply opens the file then reads each row (using the CSV library) and calls API access function create_network_path()
(which talks to the POST /v3/path endpoint) with the information retrieved. For each successful creation, it prints a message showing what was created. Otherwise, it prints an error message.
Note that the network path target location cannot be added when the network path is created. Instead, it must be added afterwards using the API access function add_network_path_location()
. It uses the PUT /v3/path/{id}/targetLocation endpoint to add the target location information to the path.
If you run app-appliances.py (e.g. python3 app-appliances.py
) you can find organization IDs and Monitoring Point names to use in the paths.csv file. Once paths.csv is updated, you can run paths-create.py (e.g. python3 paths-create.py
) to create the specified paths.
paths-delete.py and paths-show.py are similar but they delete paths and show paths that match the information in paths.csv.
Data aggregation
In order to reduce the volume of data stored and returned by calls to the API, test results are aggregated over time. Depending on how far in the past you are looking at and the size of the time range you specify, the data will either not be aggregated, be aggregated by the hour, or be aggregated by the day. If you are using the API to extract test data you’ll need to take this into consideration. The aggregation-test.py program can be used to see aggregation within your data. The code looks as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
|
Run app-network-path-info.py (e.g. python3 app-network-path-info.py
) to find an organization ID and corresponding network path ID. Update org_id and path_id with this information then run the program (e.g. python3 aggregation-test.py
). Look at “Period=” and see if/how it changes. It will either show “None” (indicating non-aggregated data), “60” (indicating data aggregated over an hour), or “1440” (indicating data aggregated over a day). You can also update hours_back and hour_range to change the time range and see how the “Period=” results change.
Last hour of data returned by default
For endpoints where a time range can be specified with optional “to” and “from” parameters (for example GET /v3/path/data, called by API access function get_network_path_stats()
), if “to” and “from” are not passed, the endpoint will return data for the last hour. To see this, in aggregation-test.py:
- Set org_id and path_id to valid values (use
python3 app-network-path-info.py
to find valid values). - Set hours_back and hour_range to 0 (which means start and end are set to None when passed to
get_network_path_stats()
). - Run the program (e.g.
python3 aggregation-test.py
).- You’ll see data from the past hour.
Differences between dual- and single-ended path data
For dual-ended paths, data is collected for both inbound and outbound directions. For single-ended paths, data is collected only in the outbound direction. This can be seen in the data returned by the GET /v3/path/data endpoint (called by API access function get_network_path_stats()
). For a given network path, the test data can be seen under “dataInbound” and “dataOutbound” for dual-ended paths and under “data” for single-ended paths. Also, “instrumentation” is set to “TWO_WAY” for dual-ended paths and “ONE_WAY” for single-ended paths. To see this, in aggregation-test.py:
- Set org_id and path_id to valid values (use
python3 app-network-path-info.py
to find valid values).- Note whether the selected network path is dual-ended or single-ended.
- Set hours_back and hour_range to 0 (to reduce the amount of data returned).
- Uncomment the
pp_json(network_path_stats)
line. - Run the program and redirect output into a file (e.g.
python3 aggregation-test.py > outfile
).- Open the output file.
- You’ll see test data under “dataInbound” and “dataOutbound” if the path is dual-ended and under “data” if the path is single-ended. You will also see “instrumentation” set to either “TWO_WAY” or “ONE_WAY”.
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.