3 Simple ways to use Cisco DNA Center Platform APIs
The Cisco Catalyst 9000 series is mainly used for Campus Networks and it can be managed through a central controller, called Cisco DNA Center.
This controller allows the administrators to deploy, manage, configure the network to meet the needs for their Business.
All through a modern looking Web UI.
But what if you want to integrate this with other tools or services?
Let’s have look at Cisco DNA Center Platform API
Cisco DNA Center Platform API
You could almost think about Cisco DNA Center as an API gateway for your network.
Instead of asking every individual network component about their information. You can retrieve it directly from Cisco DNA Center.
Same goes for configuring a service for several devices and sites.
You define the service, deploy it to the network and
Cisco DNA Center will take care of those network related changes.
Here’s a couple of APIs that collects data or creates workflow to automate services.
Get Device list
/dna/intent/api/v1/network-device
Returns a list of network devices
Get Enterprise SSID
/dna/intent/api/v1/enterprise-ssid
Returns a list of Wireless Networks
AP Provision
/dna/intent/api/v1/wireless/ap-provision
Provision Wireless Access Points
Create Application Set
/dna/intent/api/v1/application-policy-application-set
Create new custom application-set for the Network
Claim a Device to a Site
/dna/intent/api/v1/onboarding/pnp-device/site-claim
Claim a network device based on Cisco DNA Center Site based design process
Making API calls towards Cisco DNA Center Platform
Let’s make our first API call towards Cisco DNA Center Platform API, using Python 🐍.
(Any language can be used together with this REST API)
Authentication
This is the first step to receive a Token that later can be used with any API call together with Cisco DNA Center.
{'Token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZTlkYmI3NzdjZDQ3ZTAwNGM2N2RkMGUiLCJhdXRoU291cmNlIjoiaW50ZXJuYWwiLCJ0ZW5hbnROYW1lIjoiVE5UMCIsInJvbGVzIjpbIjVkYzQ0NGQ1MTQ4NWM1MDA0YzBmYjIxMiJdLCJ0ZW5hbnRJZCI6IjVkYzQ0NGQzMTQ4NWM1MDA0YzBmYjIwYiIsImV4cCI6MTU5OTc2OTM3OCwiaWF0IjoxNTk5NzY1Nzc4LCJqdGkiOiJmNzY1YTQwMy1iNGU4LTQ2YTQtODllZS00N2MwYTYxODllMDUiLCJ1c2VybmFtZSI6ImRldm5ldHVzZXIifQ.c4uISVdeIdJqZrd_fl4Stqekp_yIn8Gx7bKoHV_IXLsImy61V1q5MGZzgeQ7dCcItFYxmXUl1MAS9oEl8ihN6xrf2a5a0PFCH3AvP5uP5oh4ei_cuEsxS-71NOlTIxV00RPt7OEMpholPpkHXnmN0CkNulpJrhCFzGBcJc6ayhjDcIUuO2wqGOcqBKEKgQmQJZs78ZvWRREOa5cHGsgI6AbHnYAn6ME9Th13iAdEHfgxHNheIDsBxDdFhARy3IYhoYzsAx2oon55SZvTBxB6N-qHe6z9jFu0mIFDlVk2lIM_5I0-PxuBGsqMTlD8neMV0G2tFnf6JAMBjcrJe5PbFQ'}We need to store this Token in header for the next API calls.
Insert it to the HTTP header, where we are telling Cisco DNA Center
to authorize this API request with this Token (x-auth-token header).
For simplicity, we’ll just store this token as a variable and assign the Token to “x-auth-token” header in the coming examples.
Python API calls with requests
Here is a couple of API calls to the Cisco DNA Center Sandbox (Always-On).(Cisco DevNet offers free membership and access to Sandbox environments)
Network-Device API
This will display what kind of network devices that Cisco DNA Center manages in it’s Inventory.
{
"response": [
{
"memorySize": "NA",
"family": "Routers",
"hostname": "asr1001-x.abc.inc",
"macAddress": "00:c8:8b:80:bb:00",
"serialNumber": "FXS1912Q1SY",
...
"type": "Cisco ASR 1001-X Router",
"location": null,
"role": "BORDER ROUTER",
"instanceUuid": "1cfd383a-7265-47fb-96b3-f069191a0ed5",
"instanceTenantId": "5dc444d31485c5004c0fb20b",
"id": "1cfd383a-7265-47fb-96b3-f069191a0ed5"
}
],
"version": "1.0"
}Enterprise-SSID API
What kind of Wireless SSID is configured on Cisco DNA Center
(Note: it’s not device level config, but something Cisco DNA Center translates to a service and configures the network device)
[{
"instanceUuid": "4a4ae766-b092-4f48-aec0-955c7d87396d",
"version": 3,
"ssidDetails": [{
"name": "DNAC-WIFI-DOT1X",
"wlanType": "Enterprise",
"enableFastLane": false,
"securityLevel": "wpa2_enterprise",
"authServer": "auth_ise",
"passphrase": "",
"trafficType": "voicedata",
"enableMACFiltering": false,
"isEnabled": true,
"isFabric": true,
"fastTransition": "Adaptive",
"radioPolicy": "Dual band operation (2.4GHz and 5GHz)",
"enableBroadcastSSID": true
}],
"groupUuid": "-1",
"inheritedGroupUuid": "",
"inheritedGroupName": ""
}, {
"instanceUuid": "95fa03a8-6839-4d22-9e15-d654a7f357e0",
"version": 3,
"ssidDetails": [{
"name": "Cisco-DNAC-Test",
"wlanType": "Enterprise",
"enableFastLane": false,
"securityLevel": "wpa2_enterprise",
"authServer": "auth_ise",
"passphrase": "",
"trafficType": "voicedata",
"enableMACFiltering": false,
"isEnabled": true,
"isFabric": true,
"fastTransition": "Adaptive",
"radioPolicy": "Dual band operation (2.4GHz and 5GHz)",
"enableBroadcastSSID": true
}],
"groupUuid": "-1",
"inheritedGroupUuid": "",
"inheritedGroupName": ""
}]Configration Template API
Cisco DNA Center allows you to create custom network configuration that can be provisioned for your network.
(Every template available in Cisco DNA Center has an versioning number tied to it. In case you want to rollback a specific version.)
{
"name": "C9300_Qos_Sup8",
"projectName": "SanJose_Mousti_project_Day1",
"projectId": "9c3ea1c3-be8a-43f1-9be3-51d28bef3e42",
"templateId": "2f84a62a-3550-43e4-b9c4-115aeca1639c",
"versionsInfo": [{
"id": "df325f50-3ad0-408a-967c-84f592ea1890",
"description": "Qos for C9300 switch",
"author": "dnacdev",
"version": "3",
"versionComment": "",
"versionTime": 1601972202609
},
{
"id": "b9fe1f8b-d072-4eb0-9896-8e1348940994",
"description": "Qos for C9300 switch",
"author": "dnacdev",
"version": "4",
"versionComment": "",
"versionTime": 1602194581105
},
{
"id": "0345f5db-1baa-4dbb-92b1-906a617b8cf7",
"description": "Qos for C9300 switch",
"author": "dnacdev",
"version": "1",
"versionComment": "",
"versionTime": 1601842116009
},
{
"id": "3723e025-5ce7-441f-9798-0d24a598851a",
"description": "Qos for C9300 switch",
"author": "dnacdev",
"version": "2",
"versionComment": "",
"versionTime": 1601845114807
},
{
"id": "6edf7a1e-69af-44cf-85df-900f2a6e50a5",
"description": "Qos for C9300 switch",
"author": "dnacdev",
"version": "5",
"versionComment": "",
"versionTime": 1602194788507
}
],
"composite": false
}List Sites
We can group devices and users based on Site Hierarchy
(If we have multiple sites, then we can have global policy/settings or tie this to sites in certain hierarchy.)
{
"response": [{
"parentId": "7b56c272-4ccd-4187-8820-b7b66fdce4be",
"additionalInfo": ["string"],
"name": "Owings Mills",
"instanceTenantId": "5dc444d31485c5004c0fb20b",
"id": "426527cd-b53b-4980-a3c0-3daa70bdcd5b",
"siteHierarchy": "7b56c272-4ccd-4187-8820-b7b66fdce4be/426527cd-b53b-4980-a3c0-3daa70bdcd5b",
"siteNameHierarchy": "Global/Owings Mills"
}]
}Postman Collection
If we want to abstract the need of learning REST APIs (initially) and the learning curve of a programming language, then Postman can be a tool that you can leverage. There’s a couple of Cisco DNA Center Postman collections out here (here and here) that is maintained by Cisco DevNet team.
With that said, Postman can be used for a variety of use cases even for the more advanced programming user.
For these REST API calls, we have been using HTTP.
The Postman Client can create the same structure of JSON payload and send it to the REST API Endpoint (in this case Cisco DNA Center).
Postman Authentication
Let’s get our Cisco DNA Center Token for API calls.
Then use the same HTTP URL for listing all the devices
with Network-Device API in Postman
Easy, no coding needed. You just need to fill out the parameters and settings (https host, credentials, uri, http method and payload).
But let’s say you want to translate this in to a HTTP request in a certain programming language (curl, python, nodejs, java, golang etc.)
Postman offers a code generator, that is based on common libraries for that programming language and with your current settings.
Cisco DNA Center Python SDK
Making the same API call with minor adjustments, can be repetitive and also resulting in creating a specific functions for specific API calls.
Instead of creating it yourself, there is something called a
Software Development Kit (SDK).
These kits will help you get started with the API calls as libraries/packages/modules, for that specific programming language.
If we then look at dnacentersdk, which is a specific Python 🐍 SDK for
Cisco DNA Center Platform API.
Rather then creating our own HTTP request, it’s all wrapped in Python functions (with documenation)
Once again we’ll authenticate against Cisco DNA Center.
pip install dnacentersdkGood thing here is that the Token is already populated within the Python Instance (dnac in this case). We don’t need to store it manually.
Next, we’ll list all devices with this instance by using dnac.devices.
devices = dnac.devices.get_device_list(family='Switches and Hubs')This approach offers less coding, as we are using the functions from the SDK.
(No need to store token, create HTTP POST and GET requests)
Same goes for error handling. We can create exceptions based on the SDK.
dnacentersdk.exceptions.ApiError: [401] Unauthorized - Authentication credentials were missing or incorrect.dnacentersdk.exceptions.ApiError: [404] Not Found - The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.
There are obviously advantages of using SDKs, but there can also be drawbacks if the SDK isn’t well documented or maintained.
API Documentation
Everything that is supported through REST APIs on Cisco DNA Center Platform API is documented both within the UI on Cisco DNA Center and on Cisco DevNet (Cisco DNA Center section).
Interactive API documentations allows you easily see what kind for parameters or sample payload is needed for the API Call, but also the possibility of trying them out.
It also offers a code generator for cURL, Python and NodeJS.
Conclusion
Using a Controller based approach with APIs will help you scale and automate in a more simple/efficient way.
It is important to highlight that there are different ways of collecting and sending structured data with REST APIs over HTTP.
We have gone through 3 simple ways that we can interact with Cisco DNA Center Platform API
(Python, Postman and SDK)
This is due to the fact that you can collect several data points in a structured JSON format, through a single API endpoint (the controller).
The alternative would be to collect the data through several different API calls. Then merge and structure the data format yourself, something that could add complexity.
Find the solution that works best for you (time invested vs results)
More resources available on Cisco DevNet
* Cisco DNA Center Platform Overview
* Learning Modules: Cisco DNA Center Programmability
* Free samples codes with Cisco DNA Center (CodeExchange)
* Awesome list of Cisco DNA Center on GitHub
Hope you enjoyed this article! Thanks!
Disclaimer: I work for Cisco as a Technical Solutions Architect
These articles are my own and not Cisco’s
