Cisco Prime Infrastructure API
Prime Infrastructure API Documentation

Tutorials

Before going through the Tutorials below, make sure you have read through the Getting Started section.

These tutorials cover the basics of how to use the following functional areas:

The examples below describe how you would use the API to address specific use cases. In these use cases, we have used some examples from the Wireless world. Let us assume, we have Prime Infrastructure managing a set of branches, some branches having a relatively large set of Access Points. We will use the API to solve the following use cases:

Using the "Device Details" API

Getting the details of the Access Points in a branch.

This scenario shows how to use basic elements of the Device Details API to navigate around and query the model. These techniques are common across all parts of this API. This scenario is basically about 2 things:

  • Using the Prime Infrastructure API to get Device information.
  • Filtering the response by Device Type and by Device Group, more specifically by Branch.

Getting device information was briefly covered in the Getting Started section. The Devices REST resource will provide a summary of information about devices. Let us start here first.

Running

  /webacs/api/v1/data/data/Devices             
              

will return a list of ALL devices in the system.

The response contains information about the request that was sent, in addition to the actual content:

            <queryResponse 
            	type="Devices" 
            	rootUrl="https://ncs-nbi-demo-1/webacs/api/v1/data" 
            	requestUrl="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices" 
            	responseType="listEntityIds">
            	<entityId url="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices/16343327" type="Devices">16343327</entityId>
            	<entityId url="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices/16343328" type="Devices">16343328</entityId>
            	....
            </queryResponse>
            

That list needs to be filtered as described above to limit the scope of the response to Access Points within a particular branch.

Let us assume the name of the branch is known to be "northwest-branch". Within Prime Infrastructure, there is the notion of "groups" that are used to combine devices into logical sets of data. In this case we know that there is a group that corresponds to the branch we are interested in. Limiting the scope of the response to that particular branch may be done bu specifying the "group" in the request URL as follows (Note that the "." before the word group identifies this as a "control parameter", rather than a simple filter parameter):

  /webacs/api/v1/data/Devices?.group="northwest-branch"      
              

In the response you can see the filtering that was specified in the request:

            	requestUrl="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices?.group="northwest-branch""
            

Furthermore, we need to add filtering by device type. This may be done by filtering on the value of the deviceType attribute:

  /webacs/api/v1/data/Devices?group="northwest-branch"&deviceType=contains("Access Point")      
              

The response to this query will be a list of all the Access Points in the "northwest-branch". You can filter on any of the attributes that are defined for a given resource type - see the detailed Documentation for a list of attributes. The syntax for filtering and a list of the available operators can be found here.

By default the response will be in XML. You may turn that to JSON, by using one of the two options described in this section of the FAQ. Also if you are expecting a very large number of results you might want to make use of paging.

Getting the details about a given device in a branch, e.g. an Access Point or a Router.

This scenario covers 2 aspects:

  • Finding and identifying a device in the network.
  • Using its ID to get details about it, whether details or statistics.

In the previous scenario, we used group filtering to reduce the scope of a query that returned a list of devices. Here we may want to filter even more, down to finding a given device through it IP Address, eg.

A similar filtering mechanism may be used here. The Devices resource lets you access generic device information. This means any attribute may be used for filtering of the response. To get the details about a given device by using its IP Address, you may use the following:

  /webacs/api/v1/data/Devices?ipAddress="192.168.8.9"              
              

The response will look as follows:

  <queryResponse type="Devices" rootUrl="https://ncs-nbi-demo-1/webacs/api/v1/data" 
             requestUrl="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices" responseType="listEntityIds">
    <entityId url="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices/16343348" type="Devices">16343348</entityId>
  </queryResponse>
              

Note that 16343348 uniquely identifies this device in the system. It may be used with other API resources, so we can use this ID to get some statistics about the Device. See the next tutorial for an example.

To get the full details in the response, add .full=true to the request. Again note the use of the "." to indicate this is a "control parameter":

  /webacs/api/v1/data/Devices?ipAddress="192.168.8.9"&.full=true             
              

The response is then complete:

  <queryResponse type="Devices" rootUrl="https://ncs-nbi-demo-1/webacs/api/v1/data" 
    requestUrl="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices/16343348" responseType="getEntity">
    <entity url="https://ncs-nbi-demo-1/webacs/api/v1/data/Devices/16343348" type="Devices" dtoType="devicesDTO">
      <devicesDTO id="16343348" displayName="16343348">
        <collectionDetail>Collection completed successfully</collectionDetail>
        <collectionTime>2012-02-25T02:00:36.509-08:00</collectionTime>
        <creationTime>2012-02-15T09:12:33.260-08:00</creationTime>
        <deviceId>16343348</deviceId>
        <deviceName>IFM_2921.yourdomain.com</deviceName>
        <deviceType>Cisco 2921 Integrated Services Router G2</deviceType>
        <ipAddress>
          <address>192.168.8.9</address>
        </ipAddress>
        <location>SJCN floor 1, 2921</location>
        <managementStatus>MANAGED_AND_SYNCHRONIZED</managementStatus>
        <manufacturerPartNr>CISCO2921/K9</manufacturerPartNr>
        <reachability>REACHABLE</reachability>
        <softwareType>IOS</softwareType>
        <softwareVersion>15.0(1)M4</softwareVersion>
      </devicesDTO>
    </entity>
  </queryResponse>              

ou can use ".full=true" even if the expected response is a list of items, such as in the previous tutorial.

  /webacs/api/v1/data/Devices?group="northwest-branch"&deviceType=contains("Access Point")&.full=true   
              

Be careful, as this can create a very large results set!

Using the "Statistics" API

The Statistics service API allows you to capture the output of some predefined statistics reports. These reports are broken down into three areas:

  • Device reports
  • Interface reports
  • Application reports

The usage of each report type is essentially the same, and the rest of this tutorial just focuses on device reports.

Retrieving "TopN" device statistics.

The following statistics report will list the "Top 5" devices in terms of CPU utilisation.

	/webacs/api/v1/op/statisticsService/device/topNCPU?topN=5&range=1
	

Note here that you always need to provide some query parameters.

  • "topN" gives you the number of devices that are to be included in the report.
  • You need to identify a time span over which the report is calculated. This can be done one of two ways:

    • "range" specifies the number of hours that are covered by the report, eg 1 means the previous hour (starting at the current time).
    • startTime and endtime, as a pair. Both of these are unix "epoch time" Long values.
<mgmtResponse rootUrl="http://danijoh2-ncs:8080/webacs/api/v1/op" requestUrl="http://danijoh2-ncs:8080/webacs/api/v1/op/statisticsService/device/topNCPU?source=root&range=1&topN=5" responseType="operation">
  <statisticsDTO>
    <childStatistics/>
    <statisticEntries>
      <statisticEntry>
        <attributeName>deviceName</attributeName>
        <displayName>Device Name</displayName><entryValue>IFM-002a</entryValue>
     </statisticEntry>
     <statisticEntry>
        <attributeName>deviceIp</attributeName>
        <displayName>Device IP Address</displayName>
        <entryValue>171.69.217.77</entryValue>
     </statisticEntry>
     <statisticEntry>
       <attributeName>curUtil</attributeName>
       <displayName>Current Utilization</displayName>
       <entryValue>9.33</entryValue>
     </statisticEntry>
 ...
      </statisticEntries>
    <statisticsName>DEVICE_TOPN_CPU_UTILIZATION</statisticsName>
  </statisticsDTO>

  <statisticsDTO>
 ...
  </statisticsDTO>
</mgmtResponse>
	

Statistics for a given device.

Statistics reports for a specific device are generally retrieved in the same manner as above, but you will need to specify the deviceIP rather than "topN" and "source".

Using the "Report Service" API

Determining the utilization of WAN ports in all branches.

In this scenario, we will explore running a Saved Report Template through Prime Infrastructure API to collect the utilization details of all WAN ports in all branches.

The simple process is as follows:

  • Define a report template using the Prime Infrastructure GUI.
  • Trigger report generation.
  • Retrieve the report results

The last two items can be performed in one step - as a synchcronous operation, or as two discrete steps - in asynchronous mode.

We'll now look at these steps in more detail

Define report template.

First, we will need to save a report template that will return the target information. This is done through the user interface in the Report Launch Pad in Prime Infrastructure. The name used to save the report template is particularly important as it will be used to identify the report to be run from the API.
This step needs to be performed in Prime Infrastructure once only to set up the expected report in advance of any call to the API.

In this particular example, we pick the WAN Traffic Analysis Summary template from the Report Launch Pad, and selecting "add".

The name of the report template (that must be unique) will be used through the API to retrieve the results. Let's use "WAN-Traffic-all-branches".

The report template contents should be configured in the user interface to match the specific report requirements. Select all the details such that all branches are included, and "Last 1 hour" as the reporting period.

Once saved, the report template is accessible through the API through the reporting service. You can view a list of all the templates that have been saved as follows :

  /webacs/api/op/reportService/templates
            

You can also filter the list of templates according to Report Category and Report Type. for example :

  /webacs/api/op/reportService/templates?reportCategory="WAN Traffic Analysis Summary"&reportType=Inventory
  

Running the report.

There are two options for running the report :

  • Synchronous mode

    In this mode, the report results are returned in the response to the api call. This mode should only be used for reports that are quickly generated. This is the default mode.

  • Asynchronous mode

    In this mode, the report generation is initiated by the api call, but a subsequent call is required to collect the result. This mode of operation should be used where report generation could be a long running operation.

The basic request is the same in both modes. From the results of the "templates" query above, (or simply by remembering the name of the report!) you can then run the required report:

  /webacs/api/op/reportService/report?reportTitle=WAN-Traffic-all-branches
            

As mentioned, the mode defaults to synchronous. Asynchronous mode is selected by passing in the query control parameter ".async=true"

  /webacs/api/op/reportService/report?reportTitle=WAN-Traffic-all-branches?.async=true
            

In both cases the reportTitle element of the response will contain a "url" attribute which can be used to access the report contents. It will be of the format below. AIn addition to getting the reports from an asynchronous call, this can also be used to "re-get" the output of a synchronous request (because the results are stored on the server). Note that the "getReport" request returns the latest output from the named report.

  /webacs/api/op/reportService/getReport?reportTitle=WAN-Traffic-all-branches
            

Report output structure.

Report results are returned in XML format.

Reports are made up of a set of "dataRows", each of which contains a number "entries". The "entries" themselves contain three elements:

  • attributeName
  • dataValue
  • displayName

You can consider these as name/value pairs, with an alternative name that can be used for "pretty" formatting.

Reports may also contain (nested) childReports. The following sample shows an extract of a report with no datarows, and a single child report.

<mgmtResponse rootUrl="https://ncs-nbi-demo-1/webacs/api/v1/op" 
    requestUrl="https://ncs-nbi-demo-1/webacs/api/v1/op/reportService/report?reportTitle=Inventory-Summary&async=false" 
    responseType="operation">
  <reportDataDTO>
    <childReports>
      <childReport>
        <dataRows>
          <dataRow>
            <entries> 
              <entry>
                <attributeName>name</attributeName>
                <dataValue>IFM_2921.yourdomain.com</dataValue>
                <displayName>Device Name</displayName>
              </entry>					
              <entry>
                <attributeName>mngmntaddrss_address</attributeName>
                <dataValue>171.69.217.76</dataValue>
                <displayName>IP Address</displayName>
              </entry>
              <entry>
                <attributeName>sysLocation</attributeName>
                <dataValue>SJCN floor 1, 2921</dataValue>
                <displayName>Location</displayName>
             </entry>
             <entry>
               <attributeName>communicationState</attributeName>
               <dataValue>Reachable</dataValue>
               <displayName>Reachability Status</displayName>
             </entry>
             ......
          </entries>
        <childReport>
      <childReports>
    <dataRows/>
    <reportDate>2012-Mar-28, 22:45:30 PDT</reportDate>
    <reportName>combined_inventory</reportName>
    <reportTitle>Inventory-Summary</reportTitle> 
    <reportUrl>https://ncs-nbi-demo-1/webacs/api/v1/op/reportService/getReport?reportTitle=Inventory-Summary</reportUrl>
  </reportDataDTO>
</mgmtResponse>