Background
What is a Software Development Kit (SDK)? Put simply a set of tools, libraries and documentation to simplify interacting with a REST API. I am super excited, as I know how much simpler it is going to make developing scripts for the Cisco DNA Center API.
The Cisco DNA Center SDK is written in python and provides a python library in PyPI and associated documentation. PyPI is the official python package index, and simplifies installation of the library.
I am going to assume you are familiar with Cisco DNA Center API, so focus on installing and using the SDK.
Installing the Cisco DNA Center SDK
The SDK is available via PyPI, so all that is required is “pip install”
I would recommend using a virtual environment. This is optional, but means you do not require root access and helps keep different versions of python libraries separate. Once created, it needs to be activated, using the “source” command.
If you logout and back in, activation needs to be repeated.
python3 -m venv env3 source env3/bin/activate
To install:
pip install dnacentersdk
You are now able to use the SDK.
Using the Cisco DNA Center SDK
This is super simple. In the past, I needed lots of python code to get an authentication token, then wrap GET/PUT/POST/DELETE REST API calls.
Using the SDK is so simple, I am going to use the python REPL (the python interactive console). To start it, simply type “python” on the command line
$ python python 3.7.2 (default, Jan 13 2019, 12:50:15) [Clang 10.0.0 (clang-1000.11.45.5)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>>
First create a connection to DNAC. Go into the REPL (above) and paste the following commands:
from dnacentersdk import api dnac = api.DNACenterAPI(base_url='https://sandboxdnac2.cisco.com:443', username='devnetuser',password='Cisco123!')
For this example, I am using the DevNet sandbox. If you want to use your own DNAC, just change the base URL and credentials. You might also require “verify=False” if you have a self signed certificate.
In the past this would have been complicated. I needed to get a token, and then make sure I used that token as a header for subsequent requests. This is all taken care of with the creation of the api.DNACenterAPI object.
Now, for the first API call. This call gets all of the network devices, and the for loop prints out the managementIP address. Note that an object is returned, rather than a json structure.
devices = dnac.devices.get_device_list() for device in devices.response: print(device.managementIpAddress)
This shows all of the steps with their output
$ python Python 3.7.2 (default, Jan 13 2019, 12:50:15) [Clang 10.0.0 (clang-1000.11.45.5)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> from dnacentersdk import api >>> dnac = api.DNACenterAPI(base_url='https://sandboxdnac2.cisco.com:443', username='devnetuser',password='Cisco123!') >>> devices = dnac.devices.get_device_list() >>> for device in devices.response: ... print(device.managementIpAddress) ... 10.10.20.51 10.10.20.81 10.10.20.82 10.10.20.80 10.10.20.241 10.10.20.250 10.10.20.242 10.10.20.243 10.10.20.244 10.10.20.245 10.10.20.246 10.10.20.247 10.10.20.248 10.10.20.249 >>>
Documentation
How do you know what methods are available to call? Official documentation is available https://dnacentersdk.readthedocs.io/en/latest/api/api.html
The API is structured around groupings of endpoints. For example, all of the endpoints for network-devices are under “devices”. In the example above, dnac.devices.get_device_list() returns all network-devices.
You can also take advantage of python’s introspection capabilities.
In the example above, a dir(dnac) will return all of the properties and methods for the dnac object. The ones of interest are highlighted
>>> dir(dnac)
['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_session', 'access_token', 'authentication', 'base_url', 'clients', 'command_runner', 'custom_caller', 'devices', 'fabric_wired', 'file', 'network_discovery', 'networks', 'non_fabric_wireless', 'path_trace', 'pnp', 'session', 'single_request_timeout', 'site_profile', 'sites', 'swim', 'tag', 'task', 'template_programmer', 'verify', 'version', 'wait_on_rate_limit']
You can then use the help() function to get more information about the particular methods available. In the example below, help for dnac.devices will show a method of get_device_list() which returns all of devices in the inventory.
>>> help(dnac.devices)
Thanks
I also want to thank @josebogarin and the team @altuscr for all the great work in putting the SDK together.
What Next?
There are a number of other blogs in this series on other aspects of Cisco DNA Center. You can find them here.
In the meantime, if you would like to learn more about Cisco DNA Center, you could visit Cisco DevNet. DevNet has further explanations about other Cisco DNA Center topics.
I am in the process of converting my older code samples to use the SDK, which I will document and share. I will also provide some more advanced examples, including tasks.
Thanks for reading.
We’d love to hear what you think. Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!
Twitter @CiscoDevNet | Facebook | LinkedIn
Visit the new Developer Video Channel
Adam,
It was our pleasure to collaborate closely with Gabi and you on this library. We are really excited about simplifying developer experience while working with DNA Center.
I'm sure this is going to speed up innovation and help customers adopt DNA Center even more.
I have tried this and it seems there is still further need to request for a token beforehand. I get a "403: Role does not have valid permissions to access the API" error. The devnet team is doing a brilliant job. Really excited!
Hi Brian,
did you try to create a connection, by explicitly providing a dnacIP username and password?
dnac = api.DNACenterAPI(base_url='https://sandboxdnac2.cisco.com:443',
username='devnetuser',password='Cisco123!')
That should generate a token for you
How can one get a demo copy of the virtual DNA appliance ?