API Quickstart

The goal of the Cisco Catalyst Center platform is to deliver world-class integration capabilities and a development environment that will drive greater partner innovations, provide seamless integration with the partner eco-system, and result in greater customer satisfaction.

Catalyst Center Platform API Overview

To view Catalyst Center API documentation through the Developer Toolkit in the Platform Portal (Figure 2). To view APIs, click Platform > Developer Toolkit.

If the Platform tab is not available, a user with super-admin permissions must install the Cisco Catalyst Center Platform application on your Catalyst Center instance. For more information, see "Deploy Catalyst Center Platform" in the Cisco Catalyst Center Platform User Guide for your release version.

Figure: Developer Toolkit on the Catalyst Center Platform tab

Developer toolkit on the Cisco DNA Center Platform

The Developer Toolkit provides documentation about each API call, organized according to functional areas of the Intent API.

Figure: Catalyst Center APIs in the Developer Toolkit

Cisco DNA Center APIs in the Developer Toolkit

If the Developer Toolkit is not available, a user with super-admin permissions must install and enable the Catalyst Center REST API bundle on your Catalyst Center instance. For more information, see "Configure Bundles" in the Cisco Catalyst Center Platform User Guide for your release version.

Click a request name to get detailed information, including the request method and URL, query parameters, request header parameters, responses, and schema, along with ways to preview or test the request.

Cisco DNA Center Platform APIs Activation

Prerequisites

In order to run the code examples featured here, you must have Python 3.6 with the requests library installed. Use pip to install the requests library as shown below:

pip install requests

You must also import HTTPBasicAuth from requests.auth.

Authentication

The Catalyst Center APIs use token-based authentication. Run the following Python script to log in:

def get_token():
    token = requests.post(
       ‘https://<cluster IP>/dna/system/api/v1/auth/token’,
       auth=HTTPBasicAuth(
           username=<username>,
           password=<password>
       ),
       headers={'content-type': 'application/json'},
       verify=False,
    )
    data = token.json()
    return data[‘Token’]

Responses and Error Codes

Responses

The Catalyst Center APIs use a task-based response architecture so that multiple requests and responses can be sent concurrently.

Therefore, all PUT, POST, and DELETE requests have a task-based response (pictured below). To view more details about the response, send a GET request to the task URL (either from a script or as a URL).

API responses for GET requests are in JSON format, as shown in the examples that follow.

Error Codes

The error codes for Catalyst Center APIs follow the standard HTTP status codes.

Occasionally error codes will contain more specific information about the request. For example, the request has the following response when the input request is not valid:

{
    ‘response’: {
        ‘errorCode’: ‘Bad request’,
        ‘message’: ‘Invalid input request’,
        ‘detail’: ‘There was an error processing the input arguments.’
    },
    ‘version’: ‘1.0’
}

Examples

View Details About a Specific Network Device in Catalyst Center

In the Device Inventory in Catalyst Center you can view information about the devices in Catalyst Center. In the figure below, you can see that there is a wireless controller with the management IP address 10.93.141.38.

Network device details

To get more information about this WLC in a JSON format, run the following script:

def get_device_from_dnac(device_ip):
    response = requests.get(
        ‘https://<cluster ip>/dna/intent/api/v1/network-device/ip-address/{}’.format(device_ip),
        headers={
            ‘X-Auth-Token’: ‘{}’.format(token),
            ‘Content-type’: ‘application/json’,
        },
        verify=False
    )
    return response.json()

A sample response looks like this:

{
    "response": [
        {
            "family": "Wireless Controller",
            "lastUpdateTime": 1668796235340,
            "macAddress": "00:0c:29:7f:8b:5d",
            "deviceSupportLevel": "Supported",
            "softwareType": "IOS-XE",
            "softwareVersion": "17.4.1",
            "serialNumber": "9L2L5LZBF76",
            "inventoryStatusDetail": "<status><general code=\"SUCCESS\"/></status>",
            "collectionInterval": "Global Default",
            "managementState": "Managed",
            "upTime": "127 days, 21:14:25.02",
            "lastUpdated": "2022-11-18 18:30:35",
            "roleSource": "AUTO",
            "apManagerInterfaceIp": "",
            "bootDateTime": "2022-07-13 21:16:35",
            "collectionStatus": "Managed",
            "hostname": "C9800-CL",
            "locationName": null,
            "managementIpAddress": "10.93.141.38",
            "platformId": "C9800-CL-K9",
            "reachabilityFailureReason": "",
            "reachabilityStatus": "Reachable",
            "series": "Cisco Catalyst 9800 Wireless Controllers for Cloud",
            "snmpContact": "",
            "snmpLocation": "",
            "associatedWlcIp": "",
            "apEthernetMacAddress": null,
            "errorCode": null,
            "errorDescription": null,
            "interfaceCount": "0",
            "lineCardCount": "0",
            "lineCardId": "",
            "managedAtleastOnce": true,
            "memorySize": "NA",
            "tagCount": "0",
            "tunnelUdpPort": null,
            "uptimeSeconds": 11049529,
            "waasDeviceMode": null,
            "type": "Cisco Catalyst 9800-CL Wireless Controller for Cloud",
            "description": "Cisco IOS Software [Bengaluru], C9800-CL Software (C9800-CL-K9_IOSXE), Version 17.4.1, RELEASE SOFTWARE (fc5) Technical Support: http://www.cisco.com/techsupport Copyright (c) 1986-2020 by Cisco Systems, Inc. Compiled Thu 26-Nov-20 23:36 by mcpre netconf enabled",
            "location": null,
            "role": "ACCESS",
            "instanceUuid": "e5facea9-6097-45b7-9c1f-1c8c7224e812",
            "instanceTenantId": "5f7f7b4e22689d00c4c923e7",
            "id": "e5facea9-6097-45b7-9c1f-1c8c7224e812"
        }
    ],
    "version": "1.0"
} 

Add a Device to Catalyst Center

Right now there is only one WLC in Catalyst Center. To add a switch, run the following Python script:

def add_device_to_dnac(dnac_ip, device_ip, snmp_version,
    snmp_ro_community, snmp_rw_community,
    snmp_retry, snmp_timeout,
    cli_transport, username, password, enable_password):

    device_object = {
        ‘ipAddress’: [
            device_ip
        ],
        ‘type’: ‘NETWORK_DEVICE’,
        ‘computeDevice’: False,
        ‘snmpVersion’: snmp_version,
        ‘snmpROCommunity’: snmp_ro_community,
        ‘snmpRWCommunity’: snmp_rw_community,
        ‘snmpRetry’: snmp_retry,
        ‘snmpTimeout’: snmp_timeout,
        ‘cliTransport’: cli_transport,
        ‘userName’: username,
        ‘password’: password,
        ‘enablePassword’: enable_password
    }

    response = requests.post(
        'https://{}/dna/intent/api/v1/network-device'.format(dnac_ip),
        data=json.dumps(device_object),
        headers={
            ‘X-Auth-Token’: ‘{}’.format(token),
            ‘Content-type’: ‘application/json’
        },
        verify=False
    )
    return response.json()

Once you run the script, you will get a response like the following:

{
    'response': {
        'taskId': '6f5a724b-f922-4cec-96c3-dc5f52693934',
        'url': '/api/v1/task/6f5a724b-f922-4cec-96c3-dc5f52693934'
    },
    'version': '1.0'
}

In the URL bar, go to http://<cluster ip>/api/v1/task/<task id>, where you will see more details about the response, including whether or not the request was successful (as indicated by the isError field).

    {
    ‘response’: {
        ‘version’:1525295288734,
        ‘startTime’:1525295288734,
        ‘endTime’:1525295288777,
        ‘isError’:false,
        ‘progress’:’’,
        ‘rootId’:’6f5a724b-f922-4cec-96c3-dc5f52693934’,
        ‘serviceType’:’Inventory service’,
        ‘id’:’6f5a724b-f922-4cec-96c3-dc5f52693934’
    },
    ‘version’:’1.0’
    }

Additional Resources

Click here for additional developer resources.

Click here for more information on Catalyst Center, including release notes, licensing information, and installation guides.