REST API Troubleshooting Checklist

You can quickly troubleshoot REST API issues and identify the main points of failure by answering the questions in the following checklist. If you answer Yes, continue to the next question, unless the instructions tell you otherwise. If you answer No to a question, you've found the problem. Follow the instructions for correcting the issue.

API Setup and Access

  1. Is the URL correct?

    Make sure you're using the correct URL with the HTTPS protocol. See Base URL.

  2. Is the API key valid?

    Each user has a unique key. DevNet sends you the API key and user name when you request time in the sandbox.

  3. Is the authorization header valid?

    Ensure that you followed the 3-step process for creating a valid authorization header: (1) concatenate the user name and API key (separated by a colon) (2) encrypt the resulting string using Base64 (3) set the authorization header value to "Basic" followed by the encoded string.

  4. Does the API user have feature access?

    User access depends on the user role. For a list of the functions each role can access, see REST API/Account Type/Role Matrix.

  5. Is the SSL certificate valid and included in your trusted store?

    The REST APIs support the HTTPS protocol (not HTTP). The Cisco API server uses an SSL certificate signed by a top tier Certificate Authority (CA) to handle HTTPS access. We recommend that you include the root certificate in your trust store (this is included by default on many platforms) and use a CA-based chain of trust, rather than hard coding the Cisco certificate in your API code.

    This caution does not apply to the DevNet environment, but it's important to be aware of the constraint.

API Coding

  1. Are the request parameters valid?

    Typically, the returned error codes will help you identify any problems with incorrect parameter values. Common problems include: improper date formats (see Date/Time Formats) and invalid values for device attributes.

  2. Is the API code able to process the error codes returned by Control Center?

    When an error occurs, Control Center returns a JSON-formatted response that contains a human-readable error message and an error code. Ensure that your code can handle all the errors that may be returned. The API documentation provides a list of possible errors for each function.

  3. Does the API response coding follow best practices?

    After checking your network connection to Control Center, review your receiver code and error handling. Ensure that your code allows for additional, unexpected items in the response. Cisco may add new return values to the APIs.

API Results and Performance

  1. Did the API call return the expected results?

    You can use a web services testing tool to set up and run API function tests and test suites to verify variable values at different stages of the API execution. Also, keep in mind that the role of the API user determines the features and data that the API call can access and return.

  2. Did the API call return data with the expected performance?

    Follow these standards to improve Control Center API performance.

    • Limit the number of active calls to one at a time and avoid concurrent API processing.
    • Do not exceed 5 calls per second.
    • Page size is limited to 50 records. Make sure your code handles pagination properly.
    • Be aware that the API calls are not intended to provide real-time monitoring of service usage. For more immediate feedback when certain conditions occur, Control Center users with web interface access use automation rules and push APIs.

    You can poll API calls that return small amounts of data more frequently (once per minute, if necessary) without affecting the overall performance of Control Center.