Join me on Nov 7 for a DevNet hosted webinar: Network Automation with pyATS, Genie and Cisco DNA Center.  The blog below is a primer for that webinar.

Integrating APIs into the pyATS automation ecosystem

Intent-based networking using Cisco Digital Network Architecture Center provides you an eagle’s eye, single-pane-of-glass view of your network… in web dashboard format… automatable through REST APIs.

There are already a few excellent blog posts on using Cisco DNA Center API/SDK within Python for your automation needs:

In this blog post, we’re going to take a look at how to integrate these APIs into the Cisco pyATS automation ecosystem.

This post assumes that you have some degree of familiarity with Cisco pyATS and DNA Center, that you have pyATS installed, and network access to a Cisco DNA Center. I’ll be using DevNet Sandbox’s always-on Cisco DNA Center v1.2.10 for demonstration.

Isn’t pyATS | Genie all about CLI and parsers?

Let’s first clarify this misconception. Cisco pyATS, and its accompanying Genie library, were built day zero to feature a core framework that is:

  • OS/Platform agnostic
  • Management protocol agnostic
  • Release agnostic
  • Scale to various forms of automation requirements and test methodologies

All the specifics, such as connectivity to devices and protocol/feature libraries, are attained through plug-ins and library implementations. For instance:

This came about as a solution to unique engineering challenges we face in day-to-day work: often times, engineers work with a wide variety of devices, release branches, and sometimes 3rd party devices (e.g., solution testing). There is a lot of value to be able to use the same infrastructure/libraries, write scripts once, and be able to reuse it across the board.

Because CLI is natively intuitive to network engineers, and we’ve amassed a large number of CLI-focused libraries and parsers – it tends to overshadow everything else. In reality, the infrastructure is geared to do a lot more.

So… How do I REST using pyATS?

The glue that links together your script, libraries, devices under test, and the specific management protocol to use (eg: CLI, REST, NETCONF) is called testbed file: a YAML-format input file that describes your topology and device connectivity.

        alias: dnac
        type: dnac
        os: dnac
                username: devnetuser
                password: "Cisco123!"
                class: rest.connector.Rest
                host: sandboxdnac2.cisco.com
                verify: False

You can find a detailed explanation of testbed YAML schema here. For now, let’s try and dissect it:


This is the top-level block that describes all of the devices in our topology.


The hostname of the device we are connecting to, along with its specific details nested underneath. It’s very important that the host name be provided accurately – for CLI connectivity, this name is used to generate the CLI prompt matching pattern.

os, type, platform

These values help the underlying infrastructure to determine the correct set of libraries to load for the given connection implementation.


Often times the device’s actual hostname can be cryptic, and a pain to repeatedly type. This field gives you the ability to name/address the device in code using an alias name, eg: PE1, CE1 – whatever makes sense topologically. In this case, we’ll call our device just “dnac”.


Username/password sets for this device, supports multiple pairs (eg, one for SSH, one for rest, etc). For DNAC REST API connectivity, the library expects the credentials to be defined under the “rest” key.


This block specifies the mechanism of how the framework should connect to the testbed device. In this particular case, we are defining a “new way-to-connect” (a.k.a. via) called ‘rest’, that:

  • uses the rest connector implementation class,
  • connecting to the host “sandboxdnac2.cisco.com”
  • and expects a self-signed certificate (do not validate certificate)

For those that find YAML syntax challenging, beyond typical IDE plugins, there’s a built-in command-line tool that helps you check whether the syntax and structure conforms to pyATS requirements:

$ pyats validate testbed dna.yaml
Loading testbed file: dna.yaml
Testbed Name:

Testbed Devices:
`-- sandboxdnac2 [dnac/dnac]

Warning Messages
- Device 'sandboxdnac2' has no interface definitions

YAML Lint Messages
13:1 error trailing spaces (trailing-spaces)

Once your testbed file is validated, the most intuitive way to try it out is to load and connect in pyATS shell to see if it worked:

$ pyats shell --testbed-file dna.yaml
Welcome to pyATS Interactive Shell
Python 3.6.8 (default, Jul 12 2019, 14:03:03)
[GCC 4.2.1 Compatible Apple LLVM 10.0.1 (clang-1001.0.46.4)]

>>> from pyats.topology import loader
>>> testbed = loader.load('dna.yaml')
>>> testbed.devices.sandboxdnac2.connect(via='rest')
Connected successfully to 'sandboxdnac2'

From here, we can issue any rest API calls specified in the documentation (API doc reference), and retrieve its json results.

>>> testbed.devices.sandboxdnac2.get('/dna/intent/api/v1/topology/site-topology').json()

Just add pyATS | Genie

Armed with this new testbed YAML file, we’ve now unlocked Cisco DNA Center automation integration with pyATS | Genie. This input file tells the infrastructure how to connect to your topology devices, and which corresponding libraries to load and use. Now you can… NetDevOps!

Snapshot, diff and compare:

  1. Learn device outputs into a snapshot
  2. Compare snapshots overtime (determining what changed programmatically)
# snapshot rest apis related to: interface, isis and ospf
# and save to folder called "initial"
bash$ genie dnac interface isis ospf --testbed-file dna.yaml --output initial

# now - if something changed, regardless of whether it was done intentionally
# or not, you can take another snapshot, and compare it against your know-good states

# take the 2nd snapshot, save it into folder "modified"
bash$ genie dnac interface isis ospf --testbed-file dna.yaml --output modified

# do a diff between the two state snapshots
bash$ genie diff initial modified
# any differences will be displayed to screen

Certification Test Automation

Before integrating a newer release of Cisco DNA Center into your network, for example, validate its various expected behaviors and functionalities:

  1. Perform action on Cisco DNAC Center using rest API, eg, deploy template to target network device using /dna/intent/api/v1/template-programmer/template/deploy
  2. Connect to southbound/managed devices, check configuration is applied successfully
  3. Verify the new operational states are within expectations

Through Cisco pyATS Genie Harness – using triggers and verifications.

Preemptive Network Maintenance/Smart Recovery:

Schedule recurring jobs against your network topology, polling data from your Cisco DNA Center, performing smart analysis in your Python script, and act accordingly, based on your business requirements, such as:

  • Collecting additional data points, integrating with other tools for reporting and analysis:
    • pushing to PubSub interfaces for consumption
    • saving to databases for analysis
  • perform automated recovery, for example: reassign application policy based on network conditions such as congestion, # of clients, etc.

The possibilities are endless.

Want to Learn More? Attend the DevNet Webinar!

Join me on Nov 7 over at BrightTalk: Network Automation with pyATS, Genie and Cisco DNA Center. In this DevNet hosted webinar, I’ll be expanding more on this topic, show you live how this integration happens, and the various things that can be done with Cisco pyATS, Genie, and DNA Center.

Meanwhile, you can also checkout Cisco DevNet CodeExchange: the code used in this blog can be found under Cisco DNAC + pyATS-Genie example. You can run it on DevNet Sandbox’s always-on DNA Center, or using your lab, and get a taste of this “Phenomenal COSMIC POWER”Hank Preston (@hfpreston).

Remember, the best way to learn about something is to hands-on try it yourself. Got questions or comments? Drop them below, or tweet @simingy on Twitter.

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


Siming Yuan

Sr. Technical Leader, Engineering

DevX, Core Software Group