Getting Started with Cisco DNA Center APIs

Save time by using a single dashboard to manage and automate your network | @timmykp

You have just received a call, the network is extremely slow or there is no connectivity altogether. You, the network engineer, is immediately thrown under the bus to figure out the cause of the outage and restore connectivity as soon as possible. In the meantime, business operations are halted and everyone, including senior executives, is waiting on you to get them back up and running. The many mind-numbing troubleshooting steps that you take next to resolve the issue is a story for another day. 

By the end of this article, you will learn: How to use the DNA Center APIs in a Python script.

Intent-Based Networking

Hence the need for intent-based networking. An intent-based network infrastructure uses controller-based automation and analytics to apply business intent to network configurations. The intent-based network continuously monitors and adjusts to ensure alignment to business intent; ensures 99.9% network uptime for instance.

Cisco has been at the forefront of advocating for an evolutionary approach to network engineering through software-defined and intent-based networking using its Digital Network Architecture (DNA Center).

The DNA Center takes on an evolutionary approach to implementing software-defined networking in your environment today, rather than having to replace your existing infrastructure with devices that support a different way of doing networking, you can leverage existing protocols such as the Simple network management protocol (SNMP) and the command-line interface (CLI) to manage your network from a centralized controller.

The DNA Center controller is used in campus and branch environments where you have both wired and wireless devices. Through a dashboard, network engineers can define network fundamentals, business, and application intent to be provisioned into the network.

The Cisco DNA Center intelligently gathers usage details and statistics from every device in your network, helping make troubleshooting easier, faster, and more consistent through sensor capabilities. It also leverages machine learning and AI capabilities to correlate data and trigger auto corrective action to implement a desired operational state. The end goal? Improving network availability and agility, a key factor as organizations transform into digital businesses.

DNA Center REST APIs

In addition, Cisco DNA Center exposes a rich set of APIs that can be used by external applications to integrate network, business, and general IT processes.

 

 

It is an open and programmable micro-service controller platform. One can consume and expand its capabilities using exposed APIs and SDKs. The Cisco DNA Center APIs are organized into five major API domains:

1. Southbound API and SDK to support 3rd party and Cisco legacy network devices beyond out-of-the-box platform support.
2. Process Integration APIs and features to facilitate lateral IT/Network workflows.
3. Cross-Domain Integration APIs and features to provide policy and assurance consistency across adjacent networking domains.
4. Northbound APIs and features enabling network-centric applications.
5. Northbound APIs and Features enabling business-centric applications

Through the use of DNA Center applications and a controller, you can centrally configure and manage many network devices using a northbound interface that abstracts you from the complexities of individual network devices.

All the capabilities of the DNA Center are exposed through a REST API that you can use with your own applications. An engineer can, for instance, write a script or application that sends commands using REST APIs to the DNA Center controller to manage network devices via an abstracted interface on the controller. Using this approach, your applications don't have to talk directly to the network infrastructure.

Policy-Based Abstraction

It also provides a policy-based abstraction whereby one can focus on the outcome that you want to achieve as opposed to focusing on the mechanism of implementing it. In other words, you tell the controller what your intent is, for instance, set up quality of service, the mechanism used to implement that intent is abstracted from you.

The easiest way to think of REST is if you go to a website such as google.com, you are executing an HTTP GET request through your browser and the website returns data to you, in addition, if you fill in a form, you are sending data to the website using a POST or PUT request and then data is returned back to you.

Northbound applications on top of the DNA Center send REST requests using protocols such as HTTP to the DNA Center, and it sends data back, so applications are talking to each other rather than a user communicating to a web server through a browser, but the concept is the same.

 

 

Application Programming Interfaces

Application programming interfaces (APIs) allow you to programmatically make changes to your network as opposed to telneting into individual devices and configuring them one by one through the command-line interface.

From experience, using Python to directly program network devices can be more difficult than using an abstracted API. When you connect to various network devices, you may end up having to do screen scraping and use expect commands to know how to configure a device.

You will have to write your application to login to that networking device based on the authentication model used, and then you'll have to program your application to configure the device by typing commands such as conf t, router OSPF 1 and so forth and so on. This could get complex very fast as you try to do advanced things, you just may end up spending a lot of time reinventing the wheel. That kind of low-level programming is abstracted through the use of the DNA Center, so the northbound API makes it a lot easier for you to program the devices.

LAB: Path Trace and Flow Analysis

Let's take a look at an application that makes use of the exposed Northbound API. The Path trace application developed by Cisco allows us to discover the path between two devices. It uses the Cisco DNA Center intent APIs to collect network topology and routing data from devices in the network. It then uses this data to troubleshoot a path between two hosts or Layer 3 interfaces.

We can get information about the statistics of the devices along the path between the reference devices. So instead of one trying to use ping or traceroute to discover how traffic moves from one point to another, Path Trace does it for us!

The API calls are targeted against an always-on Cisco DevNet DNA Center Sandbox.

DevNet Sandbox Details

• Url: https://sandboxdnac.cisco.com/
• Username: devnetuser
• Password: Cisco123!

 This DevNet Sandbox lets you:

• Access at any time without making a reservation or using a VPN connection
• Learn the DNA Center GUI or experiment with the REST API
• Access a pre-configured network topology running on genuine Cisco hardware

Because this sandbox is always available to all users, any other user may potentially overwrite your work at any time. The other caveats to an always-on DNA Center sandbox are… you cannot configure the network or devices and you cannot activate and enforce policy on network devices. I should also note there is other DNA Center sandbox’s that are reservable which provides your own private lab environment for the duration of the reservation.

 

 

How to use the DNA Center APIs in a Python script

The code for this lab is also available on Cisco Devnet's GitHub page. Open a bash terminal and change to the directory where you would like to clone the repository. Clone the repository and change into the python-path-trace folder.

Authentication

To send requests to DNA Center, you'll need its IP address or fully-qualified domain name (FQDN). In our case, it's sandboxdnac.cisco.com. We're going to write a simple python function that will generate an authentication token that DNA Center can use to authorize subsequent API requests.

First, we import the required python libraries. 'Requests' is the library of choice to make the API calls. HTTPBasicAuth is part of the requests library and is used to encode the credentials to DNA Center.

#! /usr/bin/env python

from env_lab import apicem
from time import sleep
import json
import requests
import sys
import urllib3
from requests.auth import HTTPBasicAuth
    	

Then let's write out the authentication function:

• https://{}/api/system/v1/auth/token
  Gets and encapsulates user identity and role information as a single value used to make access-control decisions.

def apic_login(host, username, password):
    """
    Use the REST API to Log into an DNA_CENTER and retrieve token
    """
    url = "https://{}/api/system/v1/auth/token".format(host)
    # payload = {"username": username, "password": password}

    # Make Login request and return the response body
    response = requests.request("POST", url, auth=HTTPBasicAuth(username, password),
                                headers=headers, verify=False)
    # print response
    return response.json()["Token"]
    	

When the above function is called. A token will be generated and printed out on screen. This will be used to authenticate subsequent API calls to the DNA Center.

We can then use the REST API to retrieve a list of hosts:

• https://{}/api/v1/host
  This is used to retrieve the list of hosts based on parameters such as hostname, IP and MAC address.

Next, we will use the REST API to get the list of network devices:

• https://{}/api/v1/network-device
  Gets the list of first 500 network devices. You can also filter out the results based on parameters such as hostname, management IP address and mac address.

Followed by gathering the interface details:

• https://{}/api/v1/interface
  This gets every interface on every network device. You can also parse the data and get only those attached to a specific interface.

We can then run the flow-analysis API:

• https://{}/api/v1/flow-analysis
  This traces a path between two IP addresses.

Let's now go ahead and run the script path_trace.py: It displays among other details, the source, and destination host details such as the MAC address and IP.

Below is a section of the script output with details about one hop in the path.

Flow Details:

****************************************

Hop 1: Network Device cat_9k_1.abc.inc

Device IP: 10.10.22.66

Device Role: ACCESS ()

Ingress Interface

--------------------

Port Name: TenGigabitEthernet1/0/1

Interface Type: Physical

Admin Status: UP

Operational Status: up

Media Type: 100/1000/2.5G/5G/10GBase

TX Speed: 1000000

Duplex Setting: FullDuplex

Port Mode: access Interface

VLAN: 1

Voice VLAN: None

Egress Interface

--------------------

Port Name: TenGigabitEthernet1/1/1

Interface Type: Physical

Admin Status: UP

Operational Status: up

Media Type: unknown

Speed: 10000000

Duplex Setting: FullDuplex

Port Mode: routed Interface

VLAN: None

Voice VLAN: None

****************************************
    	

Conclusion and future steps

We can all acknowledge that manual processes are the adversary of quick value delivery, high productivity, and security. Automation isn’t only about making tasks quicker though. It also allows the creation of repeatable environments and processes as we have seen above with this Python script. Anyone on your team could run this script, no more logging support tickets for information about network devices and their current images or device types or logging into every device and running the same CLI commands, just run the automated script.

As demonstrated, the path trace application eases and accelerates the task of connection troubleshooting using the exposed Cisco DNA Center platform APIs.

With such an application, one has barely just scratched the surface! You the network engineer is now also empowered to write your own custom applications suited to your environment and implement some really creative and efficient automation processes.

The possibilities are endless!