Cisco Prime Infrastructure API
Prime Infrastructure API Documentation

Step-by-Step Tutorial

This tutorial will walk you through our RESTFUL API step-by-step. For this tutorial, we will get the list of the first five devices, sorted by IP address, whose name ends with ".com". At each step we will link to pages with more detailed information. Please do read those pages and the rest of our documentation as we do not cover everything in this tutorial.

Step 1. Setting up your account.

Learn more about
Authentication and Authorization

First, we need to setup an account that will give us the correct permissions to access the API. If you are not an administrator then you will need an administrator to complete this step for you. As an administrator, login to the user interface, and go to Administration > Users, Roles, & AAA. Create a new user (or edit an existing one) and give it the "NBI Read" group. For the purposes of this tutorial, I've created a new user account called "user" with a password of "password".


Step 2. Finding the right API resource.

Learn more about
The API Resources

Next, we need to find an API that will give us the types of information that we need; it needs to return information about devices and include at least the IP address and name of each device. Looking through the list, we can see that the GET Devices API resource provides the information we need.


Step 3. The first query.

Learn more about
Sample REST Clients
Learn more about
Authentication and Authorization

Now that we've setup our user account and identified an API resource, we need to make a query. There are a number of REST client offerings available for you to use. Of course, you can always write your own REST client as well. But for this tutorial, we will stick with cURL. For this tutorial, the host name of my server is "my_server". So without further ado, here's our first cURL query.

curl -k "https://user:password@my_server/webacs/api/v4/data/Devices"

So let's break that down. The first switch, "-k", allows the query to succeed against servers with self-signed certificates (feel free to remove this switch for added security if you install your own certificate). After that is the URL. It starts with the application layer, https. Next is our username, a colon, and our password; this let's cURL know that it should use basic authentication. Then is the hostname of the server, followed by the path to the API resource. Please note that the path is case sensitive.

The output from your server, if you have managed devices, should look something like this.

<queryResponse type="Devices" rootUrl="https://my_server/webacs/api/v4/data"
	requestUrl="https://my_server/webacs/api/v4/data/Devices"
	responseType="listEntityIds" count="32" first="0" last="31">
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721721" type="Devices">721721</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721722" type="Devices">721722</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721723" type="Devices">721723</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721724" type="Devices">721724</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721725" type="Devices">721725</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721726" type="Devices">721726</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721727" type="Devices">721727</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721728" type="Devices">721728</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721729" type="Devices">721729</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721730" type="Devices">721730</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721731" type="Devices">721731</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721732" type="Devices">721732</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721733" type="Devices">721733</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721734" type="Devices">721734</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721735" type="Devices">721735</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721736" type="Devices">721736</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721737" type="Devices">721737</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721738" type="Devices">721738</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721739" type="Devices">721739</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721740" type="Devices">721740</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721741" type="Devices">721741</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721742" type="Devices">721742</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721743" type="Devices">721743</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721744" type="Devices">721744</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721745" type="Devices">721745</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721746" type="Devices">721746</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721747" type="Devices">721747</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721748" type="Devices">721748</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721749" type="Devices">721749</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721750" type="Devices">721750</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721751" type="Devices">721751</entityId>
	<entityId url="https://my_server/webacs/api/v4/data/Devices/721752" type="Devices">721752</entityId>
</queryResponse>

Don't worry if you see more or less "entityId" elements from your server, or if the numbers to the right don't match up; they will be different for each individual server. Looking a little closer at the response, we can see that it returns back the URL we queried, a count and some offsets ("first" and "last"), as well as a list of "entityId" elements. We'll cover how to use the count and offset values later, but for now let's focus on getting detailed information about the devices.


Step 4. Getting detailed information.

Learn more about
Response Structure

Ok, so we have a list of "entityId" elements, but the only information they carry is a url and an ID. We have two options for getting more detailed information about the devices. Those options are

  1. Get the detailed information for each device (that is, one device at a time) using the url in the "url" attribute.
  2. Get the detailed information for many devices at a time by altering our original request url.

While option 1 would give us the information we need, we'll go with option 2 in this tutorial, as it's the more efficient approach. So to get detailed information about the devices, we will execute the following query.

curl -k "https://user:password@my_server/webacs/api/v4/data/Devices?.full=true"

Note that the difference in this url compared to our previous one is the addition of the ".full=true" query string at the end of the url. The response this time looks much different; for the sake of brevity, I will only include the first device from the response.

<queryResponse type="Devices" rootUrl="https://my_server/webacs/api/v4/data"
	requestUrl="https://my_server/webacs/api/v4/data/Devices?.full=true"
	responseType="listEntityInstances" count="32" first="0" last="31">
	<entity url="https://my_server/webacs/api/v4/data/Devices/721721" type="Devices" dtoType="devicesDTO">
		<devicesDTO id="721721" displayName="721721">
			<collectionDetail><status><general code="SUCCESS"/></status></collectionDetail>
			<collectionTime>2014-10-23T10:36:51.551-07:00</collectionTime>
			<creationTime>2014-09-19T08:02:37.926-07:00</creationTime>
			<deviceId>724736</deviceId>
			<deviceName>IFM_2921.cisco.com</deviceName>
			<deviceType>Cisco 2921 Integrated Services Router G2</deviceType>
			<ipAddress>171.69.217.76</ipAddress>
			<managementStatus>MANAGED_AND_SYNCHRONIZED</managementStatus>
			<manufacturerPartNrs>
			<manufacturerPartNr>CISCO2921/K9</manufacturerPartNr>
			</manufacturerPartNrs>
			<productFamily>Routers</productFamily>
			<reachability>REACHABLE</reachability>
			<softwareType>IOS</softwareType>
			<softwareVersion>15.3(2)T</softwareVersion>
		</devicesDTO>
	</entity>
	<!-- Removed all following entity elements -->
</queryResponse>

Excellent, we can now see the detailed information about our devices. In the following steps, we'll work on getting the results sorted.


Step 5. Sorting.

Learn more about
Sorting

The API provides for the ability to sort the responses by virtually any value returned in the response. If you look back at the response from the query in step 3, you'll notice that the response was sorted by ID. By default, every API query you make will have the results come back sorted by ID. However, for this tutorial we wish to sort by IP address instead. To accomplish that, we'll further modify the query we've been using to the following.

curl -k "https://user:password@my_server/webacs/api/v4/data/Devices?.full=true&.sort=ipAddress"

Now we've added another segment to the query string, the .sort parameter, and have given it the value "ipAddress" which is the name of the response parameter we wish to sort on. With that query our output has been sorted (as before, I will only include the first response).

<queryResponse type="Devices" rootUrl="https://my_server/webacs/api/v4/data"
	requestUrl="https://my_server/webacs/api/v4/data/Devices?.full=true&.sort=ipAddress"
	responseType="listEntityInstances" count="32" first="0" last="31">
	<entity url="https://my_server/webacs/api/v4/data/Devices/721730" type="Devices" dtoType="devicesDTO">
		<devicesDTO id="721730" displayName="721730">
			<collectionDetail><status><general code="SUCCESS"/></status></collectionDetail>
			<collectionTime>2014-09-19T08:03:01.905-07:00</collectionTime>
			<creationTime>2014-09-19T08:02:38.024-07:00</creationTime>
			<deviceId>724725</deviceId>
			<deviceName>IFM-Controller1</deviceName>
			<deviceType>Cisco 5508 Wireless LAN Controller</deviceType>
			<ipAddress>171.69.217.65</ipAddress>
			<managementStatus>MANAGED_AND_SYNCHRONIZED</managementStatus>
			<productFamily>Wireless Controller</productFamily>
			<reachability>REACHABLE</reachability>
			<softwareType>Cisco Controller</softwareType>
			<softwareVersion>7.4.110.0</softwareVersion>
		</devicesDTO>
	</entity>
	<!-- Removed all following entity elements -->
</queryResponse>

Step 6. Filtering.

Learn more about
Filtering

Now that we have our sorted results we need to filter down to only those devices whose name ends with ".com". To accomplish that, we need to identify the response parameter that contains the device name. Looking at the documentation page for GET Devices tells us that the name of the response parameter that we want is "deviceName". To filter we add another segment to the query string. This time we use the name of the response parameter as the query parameter name. We can filter using either a literal or using an operator. Since we want all devices with names ending in ".com", we will use an operator. Looking at the filtering page, which lists the available operators, the "endsWith" operator seems the most appropriate. So our new cURL query with filtering will be

curl -k "https://user:password@my_server/webacs/api/v4/data/Devices?.full=true&.sort=ipAddress&deviceName=endsWith(%22.com%22)"

Note that because we wish to send quotes as part of the request, but because double quote characters cannot be sent unencoded and because cURL does not automatically encode them, we give their percent-encoded values on the command line. For other REST clients that automatically encode double quotes, you could set the URL as

https://user:password@my_server/webacs/api/v4/data/Devices?.full=true&.sort=ipAddress&deviceName=endsWith(".com")

The response from the server now is a sorted filtered list of devices. Note that the value of "count" and "last" have changed to reflect the filtering. As before, only the first response is included.

<queryResponse type="Devices" rootUrl="https://my_server/webacs/api/v4/data"
	requestUrl="https://my_server/webacs/api/v4/data/Devices?.full=true&.sort=ipAddress&deviceName=endsWith(".com")"
	responseType="listEntityInstances" count="8" first="0" last="7">
	<entity url="https://my_server/webacs/api/v4/data/Devices/721721" type="Devices" dtoType="devicesDTO">
		<devicesDTO id="721721" displayName="721721">
			<collectionDetail><status><general code="SUCCESS"/></status></collectionDetail>
			<collectionTime>2014-10-28T22:00:29.538-07:00</collectionTime>
			<creationTime>2014-09-19T08:02:37.926-07:00</creationTime>
			<deviceId>724736</deviceId>
			<deviceName>IFM_2921.cisco.com</deviceName>
			<deviceType>Cisco 2921 Integrated Services Router G2</deviceType>
			<ipAddress>171.69.217.76</ipAddress>
			<managementStatus>MANAGED_AND_SYNCHRONIZED</managementStatus>
			<manufacturerPartNrs>
			<manufacturerPartNr>CISCO2921/K9</manufacturerPartNr>
			</manufacturerPartNrs>
			<productFamily>Routers</productFamily>
			<reachability>REACHABLE</reachability>
			<softwareType>IOS</softwareType>
			<softwareVersion>15.3(2)T</softwareVersion>
		</devicesDTO>
	</entity>
	<!-- Removed all following entity elements -->
</queryResponse>

Step 7. Paging.

Learn more about
Paging

Alright, with our sorted filtered results we're almost there. The last step is limiting down the results returned to just the first five. This is where the "count", "first", and "last" values come into play. Let's start off by defining what each of these attributes means.

  • count — represents the total number of results that match the filter criteria
  • first — represents the zero-based offset of the first result returned in this query response
  • last — represents the zero-based offset of the last result returned in this query response

So "first" and "last" represent the current page, and "count" represents the how many results are available (including results not included in the current page, as we'll see later). To get different pages of results, we provide two parameters that you can use in the query string of the url.

  • .firstResult — the zero-based offset that the first result should have; defaults to 0
  • .maxResults — the number of results to return; defaults to 100, has a maximum of 1000 (which can be configured)

It is important to note is that all requests are paged, even if you don't include the parameters in your query string. The API will still page using the defaults. So to get the first five results, we need to set .maxResults equal to 5. We can leave out .firstResult, because the default value of 0 is what we would send anyway. So here's our cURL command.

curl -k "https://user:password@my_server/webacs/api/v4/data/Devices?.full=true&.sort=ipAddress&deviceName=endsWith(%22.com%22)&.maxResults=5"

And with that, we have satisfied all the goals of this tutorial. Here is the final complete response. Note how the value of "last" has changed.

<queryResponse type="Devices" rootUrl="https://my_server/webacs/api/v4/data" 
requestUrl="https://my_server/webacs/api/v4/data/Devices?.full=true&.sort=ipAddress&deviceName=endsWith(".com")&.maxResults=5"
responseType="listEntityInstances" count="8" first="0" last="4">
	<entity url="https://my_server/webacs/api/v4/data/Devices/721721" type="Devices" dtoType="devicesDTO">
		<devicesDTO id="721721" displayName="721721">
			<collectionDetail><status><general code="SUCCESS"/></status></collectionDetail>
			<collectionTime>2014-10-28T22:00:29.538-07:00</collectionTime>
			<creationTime>2014-09-19T08:02:37.926-07:00</creationTime>
			<deviceId>724736</deviceId>
			<deviceName>IFM_2921.cisco.com</deviceName>
			<deviceType>Cisco 2921 Integrated Services Router G2</deviceType>
			<ipAddress>171.69.217.76</ipAddress>
			<managementStatus>MANAGED_AND_SYNCHRONIZED</managementStatus>
			<manufacturerPartNrs>
			<manufacturerPartNr>CISCO2921/K9</manufacturerPartNr>
			</manufacturerPartNrs>
			<productFamily>Routers</productFamily>
			<reachability>REACHABLE</reachability>
			<softwareType>IOS</softwareType>
			<softwareVersion>15.3(2)T</softwareVersion>
		</devicesDTO>
	</entity>
	<entity url="https://my_server/webacs/api/v4/data/Devices/721747" type="Devices" dtoType="devicesDTO">
		<devicesDTO id="721747" displayName="721747">
			<collectionDetail><status><general code="SUCCESS"/></status></collectionDetail>
			<collectionTime>2014-09-28T22:01:16.437-07:00</collectionTime>
			<creationTime>2014-09-19T08:02:38.775-07:00</creationTime>
			<deviceId>724729</deviceId>
			<deviceName>IFM-1002a.cisco.com</deviceName>
			<deviceType>Cisco ASR 1002 Router</deviceType>
			<ipAddress>171.69.217.77</ipAddress>
			<managementStatus>MANAGED_BUT_OUTOFSYNC</managementStatus>
			<manufacturerPartNrs>
			<manufacturerPartNr>ASR1002</manufacturerPartNr>
			</manufacturerPartNrs>
			<productFamily>Routers</productFamily>
			<reachability>REACHABLE</reachability>
			<softwareType>IOS-XE</softwareType>
			<softwareVersion>15.3(2)S</softwareVersion>
		</devicesDTO>
	</entity>
	<entity url="https://my_server/webacs/api/v4/data/Devices/721728" type="Devices" dtoType="devicesDTO">
		<devicesDTO id="721728" displayName="721728">
			<collectionDetail><status><general code="SUCCESS"/></status></collectionDetail>
			<collectionTime>2014-10-28T22:00:53.711-07:00</collectionTime>
			<creationTime>2014-09-19T08:02:37.952-07:00</creationTime>
			<deviceId>724732</deviceId>
			<deviceName>test.cisco.com</deviceName>
			<deviceType>Cisco 3945E Integrated Services Router G2</deviceType>
			<ipAddress>171.69.217.78</ipAddress>
			<managementStatus>MANAGED_AND_SYNCHRONIZED</managementStatus>
			<manufacturerPartNrs>
			<manufacturerPartNr>CISCO3945-CHASSIS</manufacturerPartNr>
			</manufacturerPartNrs>
			<productFamily>Routers</productFamily>
			<reachability>REACHABLE</reachability>
			<softwareType>IOS</softwareType>
			<softwareVersion>15.1(3)T</softwareVersion>
		</devicesDTO>
	</entity>
	<entity url="https://my_server/webacs/api/v4/data/Devices/721738" type="Devices" dtoType="devicesDTO">
		<devicesDTO id="721738" displayName="721738">
			<collectionDetail>
			<collectionDetail><status><general code="SUCCESS"/></status></collectionDetail>
			</collectionDetail>
			<collectionTime>2014-10-27T22:00:10.457-07:00</collectionTime>
			<creationTime>2014-09-19T08:02:38.289-07:00</creationTime>
			<deviceId>724727</deviceId>
			<deviceName>test23456.example.com</deviceName>
			<deviceType>Cisco 892,892W Integrated Services Router G2</deviceType>
			<ipAddress>171.69.217.81</ipAddress>
			<managementStatus>MANAGED_BUT_OUTOFSYNC</managementStatus>
			<manufacturerPartNrs>
			<manufacturerPartNr>CISCO892-K9</manufacturerPartNr>
			</manufacturerPartNrs>
			<productFamily>Routers</productFamily>
			<reachability>REACHABLE</reachability>
			<softwareType>IOS</softwareType>
			<softwareVersion>15.1(2)T2</softwareVersion>
		</devicesDTO>
	</entity>
	<entity url="https://my_server/webacs/api/v4/data/Devices/721727" type="Devices" dtoType="devicesDTO">
		<devicesDTO id="721727" displayName="721727">
			<collectionDetail><status><general code="SUCCESS"/></status></collectionDetail>
			<collectionTime>2014-10-28T22:00:26.163-07:00</collectionTime>
			<creationTime>2014-09-19T08:02:37.926-07:00</creationTime>
			<deviceId>724728</deviceId>
			<deviceName>SAM-5-SJ-CM.sam.com</deviceName>
			<deviceType>Cisco WAE-574 Wide Area Application Engine</deviceType>
			<ipAddress>172.23.208.136</ipAddress>
			<managementStatus>MANAGED_AND_SYNCHRONIZED</managementStatus>
			<manufacturerPartNrs>
			<manufacturerPartNr>WAVE-574-K9</manufacturerPartNr>
			</manufacturerPartNrs>
			<productFamily>Content Networking</productFamily>
			<reachability>REACHABLE</reachability>
			<softwareType>WAAS</softwareType>
			<softwareVersion>5.3.5a</softwareVersion>
		</devicesDTO>
	</entity>
</queryResponse>

Step 8. Going forward.

From here, you could fetch the next page of the results. To do that, take the previous url, and add .firstResult to the query string. Set .firstResult equal to the value of "last" plus one. Once you've reached the point where "last" is one less than "count" you know that you've reached the last page of results.

curl -k "https://user:password@my_server/webacs/api/v4/data/Devices?.full=true&.sort=ipAddress&deviceName=endsWith(%22.com%22)&.maxResults=5&.firstResult=5"

If you're not fond of XML and would rather JSON output we support that. Add ".json" after the name of the resource, before the query string, as shown below.

curl -k "https://user:password@my_server/webacs/api/v4/data/Devices.json?.full=true&.sort=ipAddress&deviceName=endsWith(%22.com%22)&.maxResults=5"

Be sure to checkout the rest of our documentation. This tutorial only scratches the surface on what you can do with our API.