Devices Guide

Introduction

Catalyst Center has information of the devices that are part of the network. The API allows you to query that information to use it for inventory, more operations within Catalyst Center or as a source of truth of your network.

Goal

The goals of this guide are:

1. Get the sum of devices known by Catalyst Center Platform.
2. Get the list of devices.
3. Filter the list of devices by platform ID.
4. Filter the list of devices by hostname.
5. Get the information of a single device.

Endpoints and methods used

• POST /dna/system/api/v1/auth/token
• GET /dna/intent/api/v1/network-device/count
• GET /dna/intent/api/v1/network-device
• GET /dna/intent/api/v1/network-device/<device_id>

Prerequisites

For this module, we recommend that the user already has experience authenticating with Catalyst Center:

• Authentication and Authorization

Environment

This guide was developed using:

• Cisco Catalyst Center 2.3.5.x.
• Python 3.7.x

Authentication

First, we need to authenticate and retrieve a token from the API.

Note: Do not use verify=False or urllib3.disable_warnings() if you are not sure of its purpose. Read Authentication and Authorization.

import requests
from requests.auth import HTTPBasicAuth
import urllib3
urllib3.disable_warnings()

BASE_URL = 'https://<IP Address>'
AUTH_URL = '/dna/system/api/v1/auth/token'
USERNAME = '<USERNAME>'
PASSWORD = '<PASSWORD>'

response = requests.post(BASE_URL + AUTH_URL, auth=HTTPBasicAuth(USERNAME, PASSWORD), verify=False)
token = response.json()['Token']
headers = {'X-Auth-Token': token, 'Content-Type': 'application/json'}

Devices API

The devices API consists of 40 endpoints that support operations like adding a device, deleting a device, exporting the device list, or retrieving information about the wireless LAN controller a device is connected to.

Devices Count

Once the developer has the token, it is possible to get the network devices count.

DEVICES_COUNT_URL = '/dna/intent/api/v1/network-device/count'
response = requests.get(BASE_URL + DEVICES_COUNT_URL, headers = headers, verify=False)
print(response.json())

The response is a JSON object, like the following:

{
    'response': 19,
    'version': '1.0'
}

Get Device List

The devices list endpoint gets the list of devices that are managed by Catalyst Center. Using query params it is possible to filter the results by parameters like hostname, macAddress, plataformId, or others.

The following code gets all the devices:

DEVICES_URL = '/dna/intent/api/v1/network-device'
response = requests.get(BASE_URL + DEVICES_URL, headers = headers, verify=False)

We can print the device ID, hostname, and IP address with the following code:

for item in response.json()['response']:
    print(item['id'], item['hostname'], item['managementIpAddress'])

Filter

If must to filter by platform ID, we can use a query string parameter to do it:

query_string_params = {'platformId': 'C9500-40X'}
response = requests.get(BASE_URL + DEVICES_URL, headers=headers,
                        params=query_string_params, verify=False)
for item in response.json()['response']:
    print(item['id'], item['hostname'], item['managementIpAddress'])

For the next section, we will need a device ID to query the API, if we know the device name we can get the device ID by filtering by hostname:

query_string_params = {'hostname': 'CSR1Kv-01.devnet.local'}
response = requests.get(BASE_URL + DEVICES_URL, headers=headers,
                        params=query_string_params, verify=False)
device_id = response.json()['response'][0]['id']

Get Device ID

Finally, if what we are looking for is the information of a single device, we can use the Get Device by ID endpoint.

DEVICES_BY_ID_URL = '/dna/intent/api/v1/network-device/{device_id}'
response = requests.get(BASE_URL + DEVICES_BY_ID_URL.format(device_id),
                        headers=headers, verify=False)
print(response.json()['response'])

Functions

So far, we have coding without creating functions for the code. The following two links have good information to get started with functions:

• Python Primer Level 2 - Functions
• Learn Python - Functions

Code

The following two snippets will display the code with and without functions. In the following guides, we will show the final code with functions.

Without functions

# Modules import
import requests
from requests.auth import HTTPBasicAuth

# Disable SSL warnings. Not needed in production environments with valid certificates
import urllib3
urllib3.disable_warnings()

# Authentication
BASE_URL = 'https://<IP Address>'
AUTH_URL = '/dna/system/api/v1/auth/token'
USERNAME = '<USERNAME>'
PASSWORD = '<PASSWORD>'

response = requests.post(BASE_URL + AUTH_URL, auth=HTTPBasicAuth(username, PASSWORD), verify=False)
token = response.json()['Token']

# Get count of devices
headers = {'X-Auth-Token': token, 'Content-Type': 'application/json'}
DEVICES_COUNT_URL = '/dna/intent/api/v1/network-device/count'
response = requests.get(BASE_URL + DEVICES_COUNT_URL,
                        headers=headers, verify=False)

# Print device count
print(response.json()['response'])

# Get list of devices
DEVICES_URL = '/dna/intent/api/v1/network-device'
response = requests.get(BASE_URL + DEVICES_URL, headers=headers, verify=False)

# Print id, hostname and management IP
for item in response.json()['response']:
    print(item['id'], item['hostname'], item['managementIpAddress'])

# Filter devices by platform ID
query_string_params = {'platformId': 'C9500-40X'}
response = requests.get(BASE_URL + DEVICES_URL, headers=headers,
                        params=query_string_params, verify=False)
for item in response.json()['response']:
    print(item['id'], item['hostname'], item['managementIpAddress'])

# Filter devices by hostname, get one result
query_string_params = {'hostname': 'CSR1Kv-01.devnet.local'}
response = requests.get(BASE_URL + DEVICES_URL, headers=headers,
                        params=query_string_params, verify=False)
device_id = response.json()['response'][0]['id']

# Get information from one device
DEVICES_BY_ID_URL = '/dna/intent/api/v1/network-device/'
response = requests.get(BASE_URL + DEVICES_BY_ID_URL + device_id,
                        headers=headers, verify=False)
print(response.json()['response'])

With functions

The repository for this guide is here.

# Modules import
import requests
from requests.auth import HTTPBasicAuth
import sys

# Disable SSL warnings. Not needed in production environments with valid certificates
import urllib3
urllib3.disable_warnings()

# Authentication
BASE_URL = 'https://<IP Address>'
AUTH_URL = '/dna/system/api/v1/auth/token'
USERNAME = '<USERNAME>'
PASSWORD = '<PASSWORD>'

# URLs
DEVICES_COUNT_URL = '/dna/intent/api/v1/network-device/count'
DEVICES_URL = '/dna/intent/api/v1/network-device'
DEVICES_BY_ID_URL = '/dna/intent/api/v1/network-device/{device_id}'

def print_devices_info(devices):
    # Print id, hostname and management IP
    for item in devices:
        print(item['id'], item['hostname'], item['managementIpAddress'])

def get_dnac_jwt_token():
    response = requests.post(BASE_URL + AUTH_URL,
                             auth=HTTPBasicAuth(USERNAME, PASSWORD),
                             verify=False)
    token = response.json()['Token']
    return token

# Get count of devices
def get_devices_count(headers):
    response = requests.get(BASE_URL + DEVICES_COUNT_URL,
                            headers = headers,
                            verify=False)
    return response.json()['response']

# Get list of devices
def get_devices_list(headers, query_string_params):
    response = requests.get(BASE_URL + DEVICES_URL,
                            headers = headers,
                            params = query_string_params,
                            verify=False)
    return response.json()['response']

# Get information from one device
def get_devices_by_id(headers, device_id):
    response = requests.get(BASE_URL + DEVICES_BY_ID_URL.format(device_id), headers =  headers, verify=False)
    return response.json()['response']

def main():
    # obtain the Catalyst Center Auth Token
    token = get_dnac_jwt_token()
    headers = {'X-Auth-Token': token, 'Content-Type': 'application/json'}

    # Print devices count
    devices_count = get_devices_count(headers)
    print('Printing device count ...')
    print('Device count is', devices_count)

    # print devices list
    print('\nPrinting device list ...')
    response = get_devices_list(headers, {})
    print_devices_info(response)

    # print devices list filtered by hostname
    print('\nPrinting device list filtered by hostname ...')
    query_string_params = {'hostname': 'CSR1Kv-01.devnet.local'}
    response = get_devices_list(headers, query_string_params)
    print_devices_info(response)

    # print devices list filtered by platform Id
    print('\nPrinting device list filtered by platform id...')
    query_string_params = {'platformId': 'C9500-40X'}
    response = get_devices_list(headers, query_string_params)
    print_devices_info(response)

    # print device information
    print('\nPrinting device info by device id...')
    device_id = response[0]['id']
    response = get_devices_by_id(headers, device_id)
    print(response)

if __name__ == "__main__":
    main()