The Prime Infrastructure API is organized around the following functional areas: Device Details, Statistics, Reports, Template Configuration and Notifications.
Most are provided as a RESTful API, where authentication is required. Responses may be returned in XML or JSON. The syntax of the requests includes multiple operators allowing to filter, sort, and page the results. Rate Limiting is enforced through the API to avoid significant impact on system health.
The health of the API may be monitored from the UI to ensure clients are not impacting the system and response times are not degrading.
The sections below provide a high level overview of the information available through the API. They include basic samples of requests and response. For more advanced samples, continue on with the tutorials. A reference documentation for each REST resource is available as well.
The REST API makes it possible to access detailed information about devices in the system.
The Devices resource provides summary information about devices, such as device type, IP Address, software version, management status, etc. It provides a good starting point to identify a set of devices, whether filtering on a given type of devices, or by logical group (e.g. branch).
The Inventory Details resource provides a lot more details about devices. It includes details about ports, vlan interfaces, ethernet interfaces, environmental details, CDP neighbors, etc...
Device Credentials for all devices are also available through the API and will contain details about SNMP and CLI credentials as configured in the system.
Device Groups, Sites or User-Defined Groups also have a dedicated set of REST resources, allowing to navigate their hierarchy. Note that filtering by group allows the limiting of the scope of a response to a given logical group (e.g. branch, campus, etc...).
Finally, Events, Alarms and Syslogs may be accessed too. There again, filtering is available, as well as paging which allows the size of a response to be limited, and to go through a large dataset step by step.
The API is being extended into new areas, and you may find some additional resources or resource groups in the index and the API. You can navigate/query/filter/page these in exactly the same manner as the basic resources above.
These API's allows access to statistics about various aspects of either devices, or the Prime Infrastructure system itself. There really are 2 ways to get statistics information from the API:
The first option provides high level information for specific use cases. The advantage is that it is readily available to use. The second option allows the callee to tailor the result exactly to a particular need, but the corresponding report - matching the expected content - needs to be defined through the user interface before it can be triggered from the API. The advantage of the second option is in the fact that even if the API doesn't provide the exact REST resource to match the need, a report can be created in the system to deliver the result through the API.
Some of the summary information available through the API include Device Health Summary information, giving access to Memory, CPU and Interface utilization for specific devices.
Template configuration allows you to manage and deploy configuration templates through the API.
Through template configuration you can manage templates by getting lists of templates, getting a single template, uploading a new template, or deleting an old template.
Deploying templates through the API is as easy selecting a list of device Ids (which you can get from the Device Details API), then populating all of the required variables and fields with the desired values.
Name | API | Description |
---|---|---|
CLI | CLI Template Configuration | CLI or command-line interface templates are packages of CLI commands and template variables that are run on the targeted device(s). |
The reports functional area allows to manipulate reports templates through the API: list, run and collect results. Any saved report template defined in Prime Infrastructure may be run through the API. The result is made available once the report has run.
Because any report can be run through the API, it provides a very convenient mechanism to customize the API with a specific response by simply creating a tailored report and using it through the API.
Saved Report Templates may first be listed through the API. The saved report template names returned as a response should be used as the ID when attempting to run a report.
Report instances may be created and run through a POST operation with the corresponding name of the saved report template. By default, the report will be run immediately, and the result will be available in the response as an attachment.
To avoid long blocking requests through the API, in case reports are expected to be long running operations, the saved templates should be set up to be run periodically through the user interface. By doing so, it means reports are run independently of API requests, thus avoiding the load. A special flag on the request through the API can be set so that the report is not actually run, but instead the latest existing result is returned. If not result exists yet, no attachment is returned.