Quick Start

This tutorial will walk you through accessing the Cisco Business Dashboard API, performing the first query, and manipulating the results to optimize the output. Also, you will retrieve a list of devices in the inventory sorted by IP address.

Access to a Cisco Business Dashboard installation is required to make use of the API. If you do not already have Cisco Business Dashboard installed, you may download the software from the Cisco software center and run it for evaluation purposes without requiring any licenses. Registered Cisco partners may also obtain short-term access to a demonstration environment using the Partner Online Demo Service (PODS).

Step 1. Setting up an access key

First, an access key must be generated with the correct permissions to access the API.

  1. To create an access key associated with your own account, log on to the Dashboard's administration interface.
  2. Click on your username in the top right corner and select My Profile. Access keys may also be created and associated with a different user by administrators.
  3. Navigate to Administration > Users and select the user to associate with the access key.
  4. On the user profile page, click the Generate Access Key button.
  5. Then, provide a description and set a lifetime for the key. The access key ID and secret will be displayed.

Note: This is the only time the secret will be displayed. You must record the secret now or a new access key will need to be created.

The access key inherits the privileges and organizations of the associated user, and any operations performed through the API will be recorded against the associated user ID.

Learn more about Authentication and Authorization

Step 2. Generating an authorization token

Once you have obtained an access key, you need to use that key to generate an authorization token. API requests are authenticated using a JSON Web Token (JWT) as described in RFC 7519. JWTs may be generated programmatically or using offline tools. For this tutorial, use an offline tool like https://jwt.io to create a JWT manually.

A JWT is created using three elements - a header, a claim set, and a secret used to sign the JWT. For this tutorial, create a JWT using an offline tool such as https://jwt.io and using the following content for the header and claim set. Replace the content in angle brackets with appropriate values for your test environment. Use the access key secret obtained in step 1 to sign the JWT.

The JWT header is of the form:

{
    "alg": "HS256",
    "typ": "JWT",
    "kid": "<Your Access Key ID>"
}

The JWT claim set is of the form:

{
    "iss": "<Your application ID>",
    "cid": "<Your application instance>",
    "appver": "<Your application version>",
    "aud": "business-dashboard.cisco.com",
    "iat": <The current time>,
    "exp": <The expiry time for the JWT>
}

In the claim set, the values should be chosen as follows:

  • iss: An identifier for your application in domain format (e.g. myapp.example.com).
  • cid: A unique identifier for the application instance - typically a UUID. You can use a tool such as https://www.uuidgenerator.net/ to create a UUID for this tutorial.
  • appver: The version of the application (e.g. 1.0).
  • iat: The current time in Unix Epoch format. You may use a tool such as https://www.epochconverter.com/ to generate a time in epoch format.
  • exp: The expiry time for the JWT. Ensure you allow enough time to complete the tutorial. The current time plus an hour should be more than sufficient.

The resulting JWT should be similar to the following:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjVjNzg5ZmQyNDQxZWEzMDAwOGVhOGJlYiJ9.eyJpc3MiOiJteWFwcC5leGFtcGxlLmNvbSIsImNpZCI6IjhiNzdhM2FjLTdlODQtNDlkYS05MjNiLTM2NWQ3NTM2NDZiYSIsImFwcHZlciI6IjEuMCIsImF1ZCI6ImZpbmRpdC5jaXNjby5jb20iLCJpYXQiOjE1NTY2OTgwODgsImV4cCI6MTU1NjcwMTY4OH0.AJ2rvnGZ6eYj-oiR_OUBurphRW-M6mqW5Ra_0Qt-BGk

Step 3. Finding the right API resource

Next, you need to find a method that will provide the information required. In this example, the method needs to return information about devices and include at least the IP address and name of each device. The API reference (located at https://{my_server}/api/index.html on your Cisco Business Dashboard instance) lists the getNodes method that provides this information.

/v2/nodes

In the Cisco Business Dashboard API, devices are referred to as 'nodes'.

Step 4. The first query

There are many tools and clients available for you to use when testing a REST API. In this tutorial, all the examples will use cURL (https://curl.haxx.se/, readily available for most Unix-like operating systems).

So, here is the first cURL query:

curl -k -H "Authorization: Bearer SIGNED_JWT" "https://my_server/api/v2/nodes/?fields=/system-state/basic&page=0&size=20&sort=ip,asc&type=Device&hostname=switch8"

The command options are as follows:

  • The first switch, "-k", allows the query to succeed against servers with self-signed certificates and can be omitted if the Dashboard has a properly signed and trusted certificate.
  • The second switch, "-H", allows an HTTP header to be included in the request. An Authorization header must be included for authentication, and must contain the JWT generated in step 2.
  • The URL specifies the API being accessed. The URL will always use the https protocol. The server name and optional port is the same used for accessing the web UI. The path is comprised of the base resource /api followed by the api version and then the path associated with the method being called. The path is case sensitive.
  • Query parameters are used to filter and limit the output. In the example above, the node data being requested is limited to the devices' system state. The data returned is limited to devices with a hostname beginning with 'switch8' and the list is sorted by IP address in ascending order. Finally, the results are limited to first page where the page size is twenty devices - in other words, the first twenty devices matching the criteria will be returned.

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

{  
   "page":0,
   "size":20,
   "data":[  
      {  
         "id":"519939c1-6090-47d0-ab5a-e46d9ee78717",
         "system":{  
            "hostname":"switch8cca5a",
            "domain-name":"lqtcn"
         },
         "system-state":{  
            "type":"Switch",
            "online":{  },
            "ip":"192.168.8.110",
            "mac":"F4:EA:67:8C:CA:5A",
            "version":"1.4.8.6",
            "pid":"SG500X-24-K9",
            "vid":"V01",
            "model":"SG500X-24",
            "sn":"DNI1624049L",
            "vendor":"Cisco",
            "description":"SG500X-24 24-Port Gigabit with 4-Port 10-Gigabit Stackable Managed Switch",
            "states":{  },
            "capabilities":[  ],
            "latest-version":"1.4.9.4",
            "release-doc-url":"https://www.cisco.com/c/en/us/support/switches/small-business-500-series-stackable-managed-switches/products-release-notes-list.html",
            "available-images":[  ],
            "network-id":"f81a2d8b-888e-44cf-8e72-15febcdfe35a",
            "network-name":"San Jose",
            "org-id":"5c4fbe2c2bedca0006523276",
            "org-name":"crdc",
            "group-id":"5c4fbe2c2bedca0006523277",
            "group-name":"crdc-default-group"
         }
      },
      {  
         "id":"8982c8eb-ff43-48ee-8808-f9253af5baf2",
         "system":{  
            "hostname":"switch872d2e",
            "domain-name":"cisco.com"
         },
         "system-state":{  
            "type":"Switch",
            "online":{  },
            "ip":"192.168.8.147",
            "mac":"F4:EA:67:87:2D:2E",
            "version":"1.4.8.6",
            "pid":"SG500-28-K9",
            "vid":"V01",
            "model":"SG500-28",
            "sn":"DNI162703N4",
            "vendor":"Cisco",
            "description":"SG500-28 28-Port Gigabit Stackable Managed Switch",
            "states":{  },
            "capabilities":[  ],
            "latest-version":"1.4.9.4",
            "release-doc-url":"https://www.cisco.com/c/en/us/support/switches/small-business-500-series-stackable-managed-switches/products-release-notes-list.html",
            "available-images":[  ],
            "network-id":"f81a2d8b-888e-44cf-8e72-15febcdfe35a",
            "network-name":"San Jose",
            "org-id":"5c4fbe2c2bedca0006523276",
            "org-name":"crdc",
            "group-id":"5c4fbe2c2bedca0006523277",
            "group-name":"crdc-default-group"
         }
      }
   ],
   "total":2
}

The data returned will vary based on the type and current state of the devices. The response also contains a total count and paging information (page number and page size). In this example, only two devices matched the criteria.

Step 5. 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 4, you'll notice that the response was sorted by IP. If no sort parameters are specified in the query, the results returned will be sorted by ID.

sort=property name (,asc|desc), default asc.

The property name is specified as a dotted hierarcy based on the structure of the response. Multiple sorts are supported - for example 'sort=system-state.version,desc&sort=system.hostname,asc'.

Step 6. Paging

The responses for several queries can contain a great deal of data, and the getNodes query is no exception. To help limit the results returned to a manageable number, the API allows for queries to be paged. This is where the "page", "size", and "total" values in the response come into play. These parameters mean the following:

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

So "page" and "size" represent the current page, and "total" represents how many results are available including results not included in the current page.

To limit the results returned to just the first five, modify the paging parameters in the query as follows:

&page=0&size=5

Step 7. Multiple Organizations Supports

Cisco Business Dashboard supports breaking a network up into multiple organizations, and each query API can limit the scope of the results returned to a specific organization by specifying the organization id in the headers as follows:

x-ctx-org-id: 5c4fbe2c2bedca0006523276

To include this header in your cURL command:

curl -k -H "Authorization: Bearer SIGNED_JWT" -H "x-ctx-org-id: 5c4fbe2c2bedca0006523276"  "https://my_server/api/v2/nodes/?fields=/system-state/basic&page=0&size=20&sort=ip,asc&type=Device&hostname=switch8"

The organization ID is the internal ID assigned in Cisco Business Dashboard for each organization. A list of organizations and their IDs can be obtained using the getOrganizations method.

By default, if the x-ctx-org-id header is missing from the request, the API will return data from all organizations accessible to the user associated with the access key used to authenticate. This is equivalent to specifying "x-ctx-org-id: all" in the request.