Cisco DNA Center API 2.3.3
Cisco DNA Center 2.3.3

API Quickstart

The goal of the Cisco DNA 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.

Cisco DNA Center Platform API Overview

To view Cisco DNA 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 DNA Center Platform application on your Cisco DNA Center instance. For more information, see "Deploy Cisco DNA Center Platform" in the Cisco DNA Center Platform User Guide for your release version.

Figure: Developer Toolkit on the Cisco DNA 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: Cisco DNA 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 Cisco DNA Center REST API bundle on your Cisco DNA Center instance. For more information, see "Configure Bundles" in the Cisco DNA 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 Cisco DNA Center APIs use token-based authentication. Run the following Python script to log in:

python
Copydef 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 Cisco DNA 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 Cisco DNA 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:

json
Copy{
    ‘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 Cisco DNA Center

In the Device Inventory in Cisco DNA Center you can view information about the devices in Cisco DNA 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:

python
Copydef 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:

json
Copy{
    "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 Cisco DNA Center

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

python
Copydef 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:

json
Copy{
    '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).

json
Copy    {
    ‘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 Cisco DNA Center, including release notes, licensing information, and installation guides.

Next