Welcome to the Prime Infrastructure API. The API conforms to the design principles of Representational State Transfer ( REST). This page will provide you with an overview of different example use cases and workflows that the API can help you solve. If you'd rather jump right into figuring out how to get started making API queries, then check out our step-by-step tutorial.
The example use cases and workflows that we discuss here are just that: examples. Our intention is that the API will serve as a toolbox. While we have use cases in mind for each of the tools we add to this toolbox, we try to implement them in such a way that they'll be useful for use cases and scenarios beyond the ones we've thought of. So please don't see this page as an exhaustive list of use cases, but rather as a way to learn some of the things you can do with the API.
One of the more popular use cases is monitoring alarms and events raised by Prime Infrastructure. We offer Alarms, Events, and Syslogs to cover this very need.
Need to know the details of the devices Prime Infrastructure is managing? Check out the Devices and Inventory Details resources to learn about wired and wireless devices. To get more details about your wireless devices, we offer resources to cover Wireless Controllers, Access Points, and Radios. Looking for a little more detail? Then check out our more detailed and verbose resources for Wireless Controllers, Access Points, and Radios.
Need to know about the clients on your network and what they're up to? We have you covered with our Clients and Client Sessions resources. Need even more details? Then check out the Clients resource group.
With our CLI templates, you can combine the familiarity of CLI configuration with the convenience of having Prime Infrastructure securely store your device credentials and track template deployment. The API allows you to leverage this feature so that you can reap these benefits while you automate large-scale deployments or network-wide configuration changes. Get the list of CLI templates to identify which templates you have on the appliance. Not finding an out-of-the-box template that fits your needs? The API allows you to upload a new template. When you're ready, you can deploy the template; because template deployment can take some time (especially when you deploy to multiple devices), the API will spin off a background job and immediately return with the job name. You can follow the job's progress, and see information about errors it might've encountered, with the job run history resource.
Most API users seem to be interested in using the API to collect information so that they can create reports or dashboards. For these types of API users, we have a few recommendations.
First, collect the data of interest through periodic polling. Some resources (like Historical Client Counts, for example) only show recent information, which will expire and no longer be accessible by the API after a given time period. Other resources (like Client Sessions) will have records that are unlikely to be updated again (for instance, disassociated sessions). By polling at a regular interval, and filtering to only look for new or updated information since the last time you polled, you can drastically cut down on the number of API queries you need to execute.
Second, store data in a data warehouse. While we work to make the API as fast as we can, API queries that involve filtering or sorting may not always run as fast as we'd like. Usually this is because we have not indexed a parameter that you're filtering or sorting on. With a data warehouse that you control, you can decide which items are indexed, and which aren't, based on your particular needs. Furthermore, given that some API resources present only recent records (like Historical Client Counts, as shown above), by the time you need to get the data to run your report, we may no longer have it. A data warehouse gives you the flexibility to determine your own data retention periods.
Third, implement graceful error handling, especially for rate limiting (503) errors. In the case of rate limiting errors, handling the error is as simple as waiting a second or two and resending the API request. For other errors, you should capture and record the entirety of the request (including the headers) you sent, and the entirety of the response you received from the API (again, including headers). If you contact Cisco for help, having this information will accelerate resolution of the issue.