Using a Cisco Python SDK

What it is

A software development kit, or SDK, is a library that wraps a platform's API in ready made functions for a programming language.

Instead of building URLs, headers and JSON bodies yourself, you create one client object and call methods on it. The SDK sends the HTTP requests for you.

Cisco and the community publish SDKs for several platforms, mostly in Python. You need to be able to read the SDK documentation and turn it into working code.

How it works

Using an SDK follows the same four steps each time.

The four steps

1. Install the package with pip.
2. Import it and create a client object with your credentials.
3. Call the method that matches the API operation.
4. Read the result, which is normally a list or dictionary.

SDK compared with raw REST

The Meraki Python library

The Meraki Dashboard API has an official Python library. You install it with pip install meraki. It takes your API key and gives you an object with a group of methods for each area of the API.

import os
import meraki

API_KEY = os.environ["MERAKI_API_KEY"]
dashboard = meraki.DashboardAPI(API_KEY, suppress_logging=True)

orgs = dashboard.organizations.getOrganizations()
for org in orgs:
    print(org["id"], org["name"])

The method name matches the operation name in the Meraki API documentation. The call getOrganizations reads the organisations that the key can see. Results come back as Python lists of dictionaries.

Each operation takes its path parameters as normal arguments.

org_id = orgs[0]["id"]
networks = dashboard.organizations.getOrganizationNetworks(org_id)
for net in networks:
    print(net["id"], net["name"])

devices = dashboard.networks.getNetworkDevices(networks[0]["id"])

The Catalyst Center SDK

The dnacentersdk package wraps the Cisco Catalyst Center API. It logs in for you and keeps the token.

import os
from dnacentersdk import api

PASSWORD = os.environ["DNAC_PASSWORD"]
BASE_URL = os.environ["DNAC_URL"]

dnac = api.DNACenterAPI(
    username="admin",
    password=PASSWORD,
    base_url=BASE_URL,
    verify=False,
)

devices = dnac.devices.get_device_list()
for device in devices.response:
    print(device.hostname, device.managementIpAddress)

The client object handles the token request, so you do not call the authentication endpoint yourself. Results are objects that allow attribute access such as device.hostname.

The verify=False setting suits a lab with a self signed certificate. Avoid it in production.

Other SDKs

Similar packages exist for other platforms. They include Webex, Cisco UCS Manager and Intersight. They all follow the same pattern: install, create a client, call a method, read the result.

Reading SDK documentation

Look for these items in the documentation:

• The install command and the Python versions that are supported.
• How to create the client and which credentials it needs.
• The list of methods, grouped by area.
• The arguments for each method and the shape of the return value.
• Example scripts, which often come close to your task.

When the documentation lists a method such as getNetworkClients, it matches an API operation with the same name. The arguments are the path and query parameters of that operation.

Error handling

An SDK raises an exception when the API returns an error. The Meraki library raises meraki.APIError. It carries the status and the message from the response.

try:
    orgs = dashboard.organizations.getOrganizations()
except meraki.APIError as err:
    print(err)