You are Here
Cisco, Cisco DNA Center, DEVASC 200-901, REST API

Cisco DNA Center REST API calls with Postman

In this article, we will take a look at base REST API calls to the Cisco DNA Center. As in the previous post, the Postman software will be used.

Environment

For the purpose of this article, we will use a Cisco DNA Center Always-on Lab. It’s a free lab environment that everybody can access to test various functionalities.

The base URL for API calls will be https://sandboxdnac.cisco.com/dna/intent/api/v1/

For authorization, we will use the generated token. To obtain a valid token, we have to set authorization method to Basic Auth with following values:

  • Username – devnetuser
  • Password – Cisco123!

After configuring the authentication method, we have to perform a POST API call to address https://sandboxdnac.cisco.com/dna/system/api/v1/auth/token

In the response there is our token, that we will use in the future calls.

To configure authorization with token, we have to add a header with following values:

  • Key – X-Auth-Token
  • Value – Here you have to paste the generated token from the previous call response

From now on, we can perform a API calls to the Cisco DNA Center.

REST API calls

First of all, we will take a look at the network devices, that are present in the DNA Center. To fetch all network devices, we have to perform a GET request.

https://sandboxdnac.cisco.com/dna/intent/api/v1/network-device

Here’s output from the call.

{
    "response": [
        {
            "memorySize": "NA",
            "family": "Routers",
            "hostname": "asr1001-x",
            "macAddress": "00:c8:8b:80:bb:00",
            "serialNumber": "FXS1932Q1SE",
            "inventoryStatusDetail": "<status><general code=\"SUCCESS\"/></status>",
            "deviceSupportLevel": "Supported",
            "collectionStatus": "Managed",
            "apManagerInterfaceIp": "",
            "tagCount": "0",
            "tunnelUdpPort": null,
            "waasDeviceMode": null,
            "upTime": "12 days, 5:14:14.84",
            "lastUpdateTime": 1603277483820,
            "collectionInterval": "Global Default",
            "softwareType": "IOS-XE",
            "softwareVersion": "16.3.2",
            "associatedWlcIp": "",
            "bootDateTime": "2020-10-09 05:37:23",
            "errorCode": null,
            "errorDescription": null,
            "interfaceCount": "0",
            "lastUpdated": "2020-10-21 10:51:23",
            "lineCardCount": "0",
            "lineCardId": "",
            "locationName": null,
            "managementIpAddress": "10.10.22.253",
            "platformId": "ASR1001-X",
            "reachabilityFailureReason": "",
            "reachabilityStatus": "Reachable",
            "series": "Cisco ASR 1000 Series Aggregation Services Routers",
            "snmpContact": "",
            "snmpLocation": "",
            "roleSource": "MANUAL",
            "type": "Cisco ASR 1001-X Router",
            "location": null,
            "role": "CORE",
            "instanceUuid": "1cfd383a-7265-47fb-96b3-f069191a0ed5",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "1cfd383a-7265-47fb-96b3-f069191a0ed5"
        },
        {
            "memorySize": "NA",
            "family": "Switches and Hubs",
            "hostname": "cat_9k_1.abc.inc",
            "macAddress": "f8:7b:20:67:62:80",
            "serialNumber": "FCW2136L0AK",
            "inventoryStatusDetail": "<status><general code=\"SUCCESS\"/></status>",
            "deviceSupportLevel": "Supported",
            "collectionStatus": "Managed",
            "apManagerInterfaceIp": "",
            "tagCount": "0",
            "tunnelUdpPort": null,
            "waasDeviceMode": null,
            "upTime": "65 days, 3:35:28.44",
            "lastUpdateTime": 1603278382749,
            "collectionInterval": "Global Default",
            "softwareType": "IOS-XE",
            "softwareVersion": "16.6.4a",
            "associatedWlcIp": "",
            "bootDateTime": "2020-08-17 07:31:22",
            "errorCode": null,
            "errorDescription": null,
            "interfaceCount": "0",
            "lastUpdated": "2020-10-21 11:06:22",
            "lineCardCount": "0",
            "lineCardId": "",
            "locationName": null,
            "managementIpAddress": "10.10.22.66",
            "platformId": "C9300-24UX",
            "reachabilityFailureReason": "",
            "reachabilityStatus": "Reachable",
            "series": "Cisco Catalyst 9300 Series Switches",
            "snmpContact": "",
            "snmpLocation": "",
            "roleSource": "AUTO",
            "type": "Cisco Catalyst 9300 Switch",
            "location": null,
            "role": "ACCESS",
            "instanceUuid": "21335daf-f5a1-4e97-970f-ce4eaec339f6",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "21335daf-f5a1-4e97-970f-ce4eaec339f6"
        },
        {
            "memorySize": "NA",
            "family": "Switches and Hubs",
            "hostname": "cat_9k_2",
            "macAddress": "f8:7b:20:71:4d:80",
            "serialNumber": "FCW2140L039",
            "inventoryStatusDetail": "<status><general code=\"SUCCESS\"/></status>",
            "deviceSupportLevel": "Supported",
            "collectionStatus": "Managed",
            "apManagerInterfaceIp": "",
            "tagCount": "0",
            "tunnelUdpPort": null,
            "waasDeviceMode": null,
            "upTime": "65 days, 3:34:15.83",
            "lastUpdateTime": 1603278366558,
            "collectionInterval": "Global Default",
            "softwareType": "IOS-XE",
            "softwareVersion": "16.6.4a",
            "associatedWlcIp": "",
            "bootDateTime": "2020-08-17 07:32:06",
            "errorCode": null,
            "errorDescription": null,
            "interfaceCount": "0",
            "lastUpdated": "2020-10-21 11:06:06",
            "lineCardCount": "0",
            "lineCardId": "",
            "locationName": null,
            "managementIpAddress": "10.10.22.70",
            "platformId": "C9300-24UX",
            "reachabilityFailureReason": "",
            "reachabilityStatus": "Reachable",
            "series": "Cisco Catalyst 9300 Series Switches",
            "snmpContact": "",
            "snmpLocation": "",
            "roleSource": "AUTO",
            "type": "Cisco Catalyst 9300 Switch",
            "location": null,
            "role": "ACCESS",
            "instanceUuid": "3e48558a-237a-4bca-8823-0580b88c6acf",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "3e48558a-237a-4bca-8823-0580b88c6acf"
        },
        {
            "memorySize": "NA",
            "family": "Switches and Hubs",
            "hostname": "cs3850",
            "macAddress": "cc:d8:c1:15:d2:80",
            "serialNumber": "FOC1833X0AR",
            "inventoryStatusDetail": "<status><general code=\"SUCCESS\"/></status>",
            "deviceSupportLevel": "Supported",
            "collectionStatus": "Managed",
            "apManagerInterfaceIp": "",
            "tagCount": "0",
            "tunnelUdpPort": null,
            "waasDeviceMode": null,
            "upTime": "12 days, 12:15:36.80",
            "lastUpdateTime": 1603269857738,
            "collectionInterval": "Global Default",
            "softwareType": "IOS-XE",
            "softwareVersion": "16.9.5",
            "associatedWlcIp": "",
            "bootDateTime": "2020-10-08 20:29:17",
            "errorCode": null,
            "errorDescription": null,
            "interfaceCount": "0",
            "lastUpdated": "2020-10-21 08:44:17",
            "lineCardCount": "0",
            "lineCardId": "",
            "locationName": null,
            "managementIpAddress": "10.10.22.73",
            "platformId": "WS-C3850-48U-E",
            "reachabilityFailureReason": "",
            "reachabilityStatus": "Reachable",
            "series": "Cisco Catalyst 3850 Series Ethernet Stackable Switch",
            "snmpContact": "",
            "snmpLocation": "",
            "roleSource": "MANUAL",
            "type": "Cisco Catalyst38xx stack-able ethernet switch",
            "location": null,
            "role": "DISTRIBUTION",
            "instanceUuid": "de6477ad-22a2-4daa-9941-eb61cecefb34",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "de6477ad-22a2-4daa-9941-eb61cecefb34"
        }
    ],
    "version": "1.0"
}

As we can see, there are a couple of network devices. We can count them manually, but in a large environment, it could be problematic. The better way to accomplish this is to perform an API call, that will return to us the number of devices.

https://sandboxdnac.cisco.com/dna/intent/api/v1/network-device/count
{
    "response": 4,
    "version": "1.0"
}

As we can see here, there are 4 devices.

Instead of gathering all devices, we can fetch data about only one device, to do so we have to use the device id.

https://sandboxdnac.cisco.com/dna/intent/api/v1/network-device/1cfd383a-7265-47fb-96b3-f069191a0ed5

And here’s the information about specified device.

{
    "response": {
        "memorySize": "NA",
        "family": "Routers",
        "hostname": "asr1001-x",
        "macAddress": "00:c8:8b:80:bb:00",
        "serialNumber": "FXS1932Q1SE",
        "inventoryStatusDetail": "<status><general code=\"SUCCESS\"/></status>",
        "deviceSupportLevel": "Supported",
        "collectionStatus": "Managed",
        "apManagerInterfaceIp": "",
        "tagCount": "0",
        "tunnelUdpPort": null,
        "waasDeviceMode": null,
        "upTime": "12 days, 5:14:14.84",
        "lastUpdateTime": 1603277483820,
        "collectionInterval": "Global Default",
        "softwareType": "IOS-XE",
        "softwareVersion": "16.3.2",
        "associatedWlcIp": "",
        "bootDateTime": "2020-10-09 05:37:23",
        "errorCode": null,
        "errorDescription": null,
        "interfaceCount": "0",
        "lastUpdated": "2020-10-21 10:51:23",
        "lineCardCount": "0",
        "lineCardId": "",
        "locationName": null,
        "managementIpAddress": "10.10.22.253",
        "platformId": "ASR1001-X",
        "reachabilityFailureReason": "",
        "reachabilityStatus": "Reachable",
        "series": "Cisco ASR 1000 Series Aggregation Services Routers",
        "snmpContact": "",
        "snmpLocation": "",
        "roleSource": "MANUAL",
        "type": "Cisco ASR 1001-X Router",
        "location": null,
        "role": "CORE",
        "instanceUuid": "1cfd383a-7265-47fb-96b3-f069191a0ed5",
        "instanceTenantId": "5dc444d31485c5004c0fb20b",
        "id": "1cfd383a-7265-47fb-96b3-f069191a0ed5"
    },
    "version": "1.0"
}

If we’re interested in information about VLANs on a particular device, we can perform a GET API call containing device id.

https://sandboxdnac.cisco.com/dna/intent/api/v1/network-device/21335daf-f5a1-4e97-970f-ce4eaec339f6/vlan

And here’s the response.

{
    "response": [
        {
            "vlanNumber": 1,
            "numberOfIPs": 16,
            "ipAddress": "10.10.22.97",
            "prefix": "28",
            "interfaceName": "Vlan1",
            "networkAddress": "10.10.22.96"
        }
    ],
    "version": "1.0"
}

As we can see, there is one VLAN interface configured on this device.

We can also gather information about all interfaces.

https://sandboxdnac.cisco.com/dna/intent/api/v1/interface

In this example, there are plenty of network interfaces, the output has been shortened.

{
    "response": [
        {
            "pid": "ASR1001-X",
            "vlanId": "0",
            "ifIndex": "2",
            "macAddress": "00:c8:8b:80:bb:01",
            "status": "up",
            "adminStatus": "UP",
            "deviceId": "1cfd383a-7265-47fb-96b3-f069191a0ed5",
            "portName": "TenGigabitEthernet0/0/1",
            "mediaType": "unknown",
            "speed": "10000000",
            "duplex": "FullDuplex",
            "interfaceType": "Physical",
            "ipv4Address": "10.10.22.74",
            "ipv4Mask": "255.255.255.252",
            "isisSupport": "false",
            "mappedPhysicalInterfaceId": null,
            "mappedPhysicalInterfaceName": null,
            "nativeVlanId": null,
            "ospfSupport": "false",
            "portMode": "routed",
            "portType": "Ethernet Port",
            "serialNo": "FXS1932Q1SE",
            "voiceVlan": null,
            "lastUpdated": "2020-10-21 10:51:23.82",
            "series": "Cisco ASR 1000 Series Aggregation Services Routers",
            "description": "changed by DNAC 1601891716.6659918",
            "className": "EthrntPrtclEndpntExtndd",
            "instanceUuid": "9f3ac380-bd9b-47d6-a1d8-595898f0ff60",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "9f3ac380-bd9b-47d6-a1d8-595898f0ff60"
        },
        {
            "pid": "ASR1001-X",
            "vlanId": "0",
            "ifIndex": "8",
            "macAddress": "00:c8:8b:80:bb:07",
            "status": "down",
            "adminStatus": "UP",
            "deviceId": "1cfd383a-7265-47fb-96b3-f069191a0ed5",
            "portName": "GigabitEthernet0/0/5",
            "mediaType": "unknown",
            "speed": "1000000",
            "duplex": "FullDuplex",
            "interfaceType": "Physical",
            "ipv4Address": null,
            "ipv4Mask": null,
            "isisSupport": "false",
            "mappedPhysicalInterfaceId": null,
            "mappedPhysicalInterfaceName": null,
            "nativeVlanId": null,
            "ospfSupport": "false",
            "portMode": "routed",
            "portType": "Ethernet Port",
            "serialNo": "FXS1932Q1SE",
            "voiceVlan": null,
            "lastUpdated": "2020-10-21 10:51:23.82",
            "series": "Cisco ASR 1000 Series Aggregation Services Routers",
            "description": "",
            "className": "EthrntPrtclEndpntExtndd",
            "instanceUuid": "5140678d-f229-4688-aabc-75ba0cf8288f",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "5140678d-f229-4688-aabc-75ba0cf8288f"
        },
[...]

To get information about only one interface, we have to specify the interface name attribute in the header. Postman will automatically append this attribute to the request URI.

https://sandboxdnac.cisco.com/dna/intent/api/v1/interface/network-device/1cfd383a-7265-47fb-96b3-f069191a0ed5/interface-name?name=TenGigabitEthernet0/0/1

The successful response has the following structure.

{
    "response": {
        "pid": "ASR1001-X",
        "vlanId": "0",
        "ifIndex": "2",
        "macAddress": "00:c8:8b:80:bb:01",
        "status": "up",
        "adminStatus": "UP",
        "deviceId": "1cfd383a-7265-47fb-96b3-f069191a0ed5",
        "portName": "TenGigabitEthernet0/0/1",
        "mediaType": "unknown",
        "speed": "10000000",
        "duplex": "FullDuplex",
        "interfaceType": "Physical",
        "ipv4Address": "10.10.22.74",
        "ipv4Mask": "255.255.255.252",
        "isisSupport": "false",
        "mappedPhysicalInterfaceId": null,
        "mappedPhysicalInterfaceName": null,
        "nativeVlanId": null,
        "ospfSupport": "false",
        "portMode": "routed",
        "portType": "Ethernet Port",
        "serialNo": "FXS1932Q1SE",
        "voiceVlan": null,
        "lastUpdated": "2020-10-21 10:51:23.82",
        "series": "Cisco ASR 1000 Series Aggregation Services Routers",
        "description": "changed by DNAC 1601891716.6659918",
        "className": "EthrntPrtclEndpntExtndd",
        "instanceUuid": "9f3ac380-bd9b-47d6-a1d8-595898f0ff60",
        "instanceTenantId": "5dc444d31485c5004c0fb20b",
        "id": "9f3ac380-bd9b-47d6-a1d8-595898f0ff60"
    },
    "version": "1.0"
}

Cisco DNA Center has a bunch of attributes that inform us about the overall network health. We can get it using a single API call.

https://sandboxdnac.cisco.com/dna/intent/api/v1/network-health
{
  "version" : "1.0",
  "response" : [ {
    "time" : "2020-10-21T14:30:00.000+0000",
    "healthScore" : 100,
    "totalCount" : 4,
    "goodCount" : 4,
    "unmonCount" : 0,
    "fairCount" : 0,
    "badCount" : 0,
    "entity" : null,
    "timeinMillis" : 1603290600000
  } ],
  "measuredBy" : "global",
  "latestMeasuredByEntity" : null,
  "latestHealthScore" : 100,
  "monitoredDevices" : 4,
  "monitoredHealthyDevices" : 4,
  "monitoredUnHealthyDevices" : 0,
  "unMonitoredDevices" : 0,
  "healthDistirubution" : [ {
    "category" : "Core",
    "totalCount" : 1,
    "healthScore" : 100,
    "goodPercentage" : 100,
    "badPercentage" : 0,
    "fairPercentage" : 0,
    "unmonPercentage" : 0,
    "goodCount" : 1,
    "badCount" : 0,
    "fairCount" : 0,
    "unmonCount" : 0
  }, {
    "category" : "Access",
    "totalCount" : 2,
    "healthScore" : 100,
    "goodPercentage" : 100,
    "badPercentage" : 0,
    "fairPercentage" : 0,
    "unmonPercentage" : 0,
    "goodCount" : 2,
    "badCount" : 0,
    "fairCount" : 0,
    "unmonCount" : 0
  }, {
    "category" : "Distribution",
    "totalCount" : 1,
    "healthScore" : 100,
    "goodPercentage" : 100,
    "badPercentage" : 0,
    "fairPercentage" : 0,
    "unmonPercentage" : 0,
    "goodCount" : 1,
    "badCount" : 0,
    "fairCount" : 0,
    "unmonCount" : 0
  } ]
}

For the last example, we will look at the OSPF interfaces. We can list all of them by sending the following API request.

https://sandboxdnac.cisco.com/dna/intent/api/v1/interface/ospf
{
    "response": [
        {
            "pid": "C9300-24UX",
            "vlanId": "1",
            "ifIndex": "49",
            "macAddress": "f8:7b:20:71:4d:c7",
            "status": "up",
            "adminStatus": "UP",
            "deviceId": "3e48558a-237a-4bca-8823-0580b88c6acf",
            "portName": "Vlan1",
            "mediaType": null,
            "speed": "1000000",
            "duplex": null,
            "interfaceType": "Virtual",
            "ipv4Address": "10.10.22.113",
            "ipv4Mask": "255.255.255.240",
            "isisSupport": "false",
            "mappedPhysicalInterfaceId": null,
            "mappedPhysicalInterfaceName": null,
            "nativeVlanId": null,
            "ospfSupport": "true",
            "portMode": "routed",
            "portType": "Ethernet SVI",
            "serialNo": "FCW2140L039",
            "voiceVlan": null,
            "lastUpdated": "2020-10-21 11:06:06.558",
            "series": "Cisco Catalyst 9300 Series Switches",
            "description": "",
            "className": "VLANInterfaceExtended",
            "instanceUuid": "b0270245-4b2c-486e-9fcd-061e8a04dc68",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "b0270245-4b2c-486e-9fcd-061e8a04dc68"
        },
        {
            "pid": "C9300-24UX",
            "vlanId": "1",
            "ifIndex": "49",
            "macAddress": "f8:7b:20:67:62:c7",
            "status": "up",
            "adminStatus": "UP",
            "deviceId": "21335daf-f5a1-4e97-970f-ce4eaec339f6",
            "portName": "Vlan1",
            "mediaType": null,
            "speed": "1000000",
            "duplex": null,
            "interfaceType": "Virtual",
            "ipv4Address": "10.10.22.97",
            "ipv4Mask": "255.255.255.240",
            "isisSupport": "false",
            "mappedPhysicalInterfaceId": null,
            "mappedPhysicalInterfaceName": null,
            "nativeVlanId": null,
            "ospfSupport": "true",
            "portMode": "routed",
            "portType": "Ethernet SVI",
            "serialNo": "FCW2136L0AK",
            "voiceVlan": null,
            "lastUpdated": "2020-10-21 11:06:22.749",
            "series": "Cisco Catalyst 9300 Series Switches",
            "description": "",
            "className": "VLANInterfaceExtended",
            "instanceUuid": "b359bd4d-9f68-4d1b-adfc-eda2f9c45e78",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "b359bd4d-9f68-4d1b-adfc-eda2f9c45e78"
        },
        {
            "pid": "C9300-24UX",
            "vlanId": null,
            "ifIndex": "36",
            "macAddress": "f8:7b:20:67:62:80",
            "status": "up",
            "adminStatus": "UP",
            "deviceId": "21335daf-f5a1-4e97-970f-ce4eaec339f6",
            "portName": "TenGigabitEthernet1/1/1",
            "mediaType": "SFP-10GBase-CX1",
            "speed": "10000000",
            "duplex": "FullDuplex",
            "interfaceType": "Physical",
            "ipv4Address": "10.10.22.66",
            "ipv4Mask": "255.255.255.252",
            "isisSupport": "false",
            "mappedPhysicalInterfaceId": null,
            "mappedPhysicalInterfaceName": null,
            "nativeVlanId": null,
            "ospfSupport": "true",
            "portMode": "routed",
            "portType": "Ethernet Port",
            "serialNo": "FCW2136L0AK",
            "voiceVlan": null,
            "lastUpdated": "2020-10-21 11:06:22.749",
            "series": "Cisco Catalyst 9300 Series Switches",
            "description": "P2P link cs3850",
            "className": "SwitchPort",
            "instanceUuid": "d7fc6810-1ad7-4502-bb4c-46063909cf78",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "d7fc6810-1ad7-4502-bb4c-46063909cf78"
        },
        {
            "pid": "C9300-24UX",
            "vlanId": null,
            "ifIndex": "36",
            "macAddress": "f8:7b:20:71:4d:80",
            "status": "up",
            "adminStatus": "UP",
            "deviceId": "3e48558a-237a-4bca-8823-0580b88c6acf",
            "portName": "TenGigabitEthernet1/1/1",
            "mediaType": "SFP-10GBase-CX1",
            "speed": "10000000",
            "duplex": "FullDuplex",
            "interfaceType": "Physical",
            "ipv4Address": "10.10.22.70",
            "ipv4Mask": "255.255.255.252",
            "isisSupport": "false",
            "mappedPhysicalInterfaceId": null,
            "mappedPhysicalInterfaceName": null,
            "nativeVlanId": null,
            "ospfSupport": "true",
            "portMode": "routed",
            "portType": "Ethernet Port",
            "serialNo": "FCW2140L039",
            "voiceVlan": null,
            "lastUpdated": "2020-10-21 11:06:06.558",
            "series": "Cisco Catalyst 9300 Series Switches",
            "description": "P2P link cs3850",
            "className": "SwitchPort",
            "instanceUuid": "e623c7cf-a862-441b-97c5-72aaba2d5d17",
            "instanceTenantId": "5dc444d31485c5004c0fb20b",
            "id": "e623c7cf-a862-441b-97c5-72aaba2d5d17"
        }
    ],
    "version": "1.0"
}

Summary

I hope that the presented examples will help you while building API calls for your own purposes. If you would like to dive more into the Cisco DNA Center REST API, make sure to check the official documentation.

Share

Related Posts

3 thoughts on “Cisco DNA Center REST API calls with Postman”

  1. Pingback:Cisco DNA REST API calls with Python’s requests library - garzum.net

  2. Hi,

    I’m having some trouble with a simple DNA Center query that doesnt seen to be covered in the documentation.
    I want to list the sites and limit what attributes are returned, something like:
    https://dnac_url/dna/intent/api/v1/site/&fields=id,name,type

    It seems the “&fields=id,name,type” syntax isnt available on this API. Do you know if this is the case or if there is another way to achieve this?
    thanks.

    1. Hi Brian. I haven’t touched a DNA Center API much besides articles present on this blog, but I don’t recall such functionality to limit returned attributes of particular objects.

Leave a Reply

Your email address will not be published. Required fields are marked *