
Cisco Evolved Programmable Network Manager API
Evolved Programmable Network Manager API Documentation

# Frequently Asked Questions

Additional answers may be found in the getting started section about the Evolved Programmable Network Manager API, and in the tutorial.

1. What is the syntax for requests to the Evolved Programmable Network Manager API?
2. XML or JSON in the response?
3. How do I reduce API latency and increase throughput?
4. Why am I sometimes receiving HTTP 503 errors?
5. I'm using TACACS/ACS, why am I periodically getting 401 errors?
6. Why do response parameters sometimes come as an object and other times as an array when using JSON?
7. Why do I sometimes get empty HTTP 400 responses? Why must I encode double quote characters? (CSCvf16644)
8. Why some resources return an incorrect date or time?

#### 1. What is the syntax for requests to the Evolved Programmable Network Manager API?

The general structure of a request to the Evolved Programmable Network Manager API is as follows:

      ../webacs/api/v4/data/{RESOURCE-NAME}

This will list all instances of that resource. For example, ../webacs/api/v4/data/Devices will return a list of all Device instances in the system.

      ../webacs/api/v4/data/{RESOURCE-NAME}/{RESOURCE-ID}

This will return the unique instance identified by the given {RESOURCE-ID}. For example, ../webacs/api/v4/data/Devices/12412764 returns the "12412764" device.

Qualifiers may be added to use filtering, paging and sorting following this format:

      ../webacs/api/v4/data/{RESOURCE-NAME}?{operator-expression1}&{operator-expression2}...&{operator-expressionN}

Each operator expression may be a filtering criteria such as ipAddress="192.168.1.3", or a paging directive, or a sorting directive, such as .sort=-collectionTime.

Optionally, the .full=true qualifier may be added to return the full instance.

Additional RESTful services are available through the following URL pattern:

      ../webacs/api/v4/op/{service-domain}/{service-resource}

For example, ../webacs/api/op/reportservice/templates provides a way to list all report templates that may be used to create reports.

#### 2. XML or JSON in the response?

The response to a request to the Evolved Programmable Network Manager API may be returned in one of two standard formats: XML or JSON. The format of the response may be specified in one of two ways:

- By adding ".json" or ".xml" to the URL, at the end of the path but before the query string. For example:

        ../webacs/api/v4/data/Devices.json?ipAddress="192.168.8.9"

  returns a response in JSON format, whereas

        ../webacs/api/v4/data/Devices.xml?ipAddress="192.168.8.9"

  returns a response in XML format.
- By specifying the expected format in the request "Accept" header:

        Accept: application/json

  returns a response in JSON format, whereas

        Accept: text/xml

  returns a response in XML format.

By default, when nothing is specified, the response format is set to be XML.

#### 3. How do I reduce API latency and increase throughput?

If you would like to cut down the latency of API requests, or improve throughput, you can try some of the following tips:

- For queries against resources that support paging, try using the ".nocount" parameter and set it to true. For example

        ../webacs/api/v4/data/Devices?.nocount=true

  Doing so will remove the "count," "first," and "last" attributes from the API response. However, the API will require one less query against the underlying data source, yielding a lower latency.
- Consider using Summary resources if they report all the information you need. API latency can be reduced by using resources that return more limited sets of information. For instance, if you wish to get the IP addresses of clients, then Client Summary will report the data you need faster than Client Details.
- Use larger page sizes for resources that support paging. While it might seem counter-intuitive, most of the performance costs paid by the API are on a per-request basis, not a per-record basis. By increasing page sizes, you can reduce the overall number of requests and increase your overall throughput.
- Check the documentation to ensure the resource you're using is not deprecated or does not have a newer version.

#### 4. Why am I sometimes receiving HTTP 503 errors?

If you sometimes receive HTTP 503 errors, but at other times receive a success response, you are being rate limited. The best thing to do in this case is to wait for a few seconds and try the same request again. For more details, please see our rate limiting documentation.

#### 5. I'm using TACACS/ACS, why am I periodically getting 401 errors?

When your Evolved Programmable Network Manager is configured to do AAA through TACACS/ACS, you will sometimes get periodic or random 401 errors. This is because of timeouts and unresponsiveness in the connection between Evolved Programmable Network Manager and the ACS server. To help reduce the frequency of these events, please increase the timeout and retry count that you've configured in the settings for Evolved Programmable Network Manager.

#### 6. Why do response parameters sometimes come as an object and other times as an array when using JSON?

This is a known issue when using JSON and the v1 API. We recommend switching to the v3 (or v2) API to address this issue.

#### 7. Why do I sometimes get empty HTTP 400 responses? Why must I encode double quote characters? (CSCvf16644)

To address a security vulnerability, third party software used in Evolved Programmable Network Manager was changed to no longer accept any characters in a URL outside of the reserved and unreserved characters defined in RFC 3986. When such characters are received, an empty HTTP 400 response is sent. To avoid this issue, percent-encode characters not valid in a URL, like double quotes (change double quotes to '%22'). Note that some clients will automatically encode such characters.

#### 8. Why some resources return an incorrect date or time?

This is a known issue when using v1-v4 API. Several API resources return dates in ISO-8601 format with an incorrect UTC offset when the appliance is not in the UTC-0 time zone.

To get the correct date you need to add the UTC offset configured on the appliance to the date reported by the API. For example, if an API resource returns "2018-10-20T19:00:00-04:00" and the appliance uses UTC-4 time zone, then the correct date is "2018-10-20T15:00:00-04:00".

Affected resources:

- data/ApOnboardingProfile
- data/GuestUsers
- v4/data/HistoricalRFCounters
- v4/data/HistoricalRFLoadStats
- v4/data/HistoricalRFStats
- v4/data/RFCounters
- v4/data/RFLoadStats
- v4/data/RFStats
- data/Syslogs
- v4/data/WlanControllerDetails

- Tutorials
- FAQ
- API Versioning