Catalyst Center and SD-WAN Manager APIs

What it is

Catalyst Center and SD-WAN Manager both expose REST APIs, so scripts and other tools can do what the graphical interface does.

An API call is an HTTPS request to a path on the controller, and the answer comes back as JSON. Because the controller manages many devices, one API call can read or change a whole network. Both controllers use token or session based login, and both are described by documentation on the controller itself.

How it works

Each controller has its own login method, path layout and data format.

Catalyst Center APIs

Catalyst Center offers several groups of API.

The Intent API is the one that you use most. Paths for it start with /dna/intent/api/, followed by a version.

Catalyst Center authentication

A client logs in once, receives a token, and sends the token on later calls.

POST /dna/system/api/v1/auth/token HTTP/1.1
Host: catalyst.example
Authorization: Basic BASE64OFUSERNAMEANDPASSWORD

The reply holds a token. The client then adds it to a header named X-Auth-Token.

GET /dna/intent/api/v1/network-device HTTP/1.1
Host: catalyst.example
X-Auth-Token: TOKENVALUE
Accept: application/json

The reply is a JSON object with a response key that holds a list of devices, and a version key. Each device entry has fields such as the host name, the management address, the platform and the software version.

{
  "response": [
    {
      "hostname": "sw1.example",
      "managementIpAddress": "10.1.1.11",
      "platformId": "C9300-24P",
      "softwareVersion": "17.9.4",
      "reachabilityStatus": "Reachable"
    }
  ],
  "version": "1.0"
}

Some calls run a task in the background. In that case the controller answers at once with a task identifier, and the client asks for the task status until it is finished.

Catalyst Center in Python

import requests
from urllib.parse import urlunsplit

HOST = "catalyst.example"
auth_url = urlunsplit(("https", HOST, "/dna/system/api/v1/auth/token", "", ""))
reply = requests.post(auth_url, auth=("admin", "PASSWORD"), verify=False)
token = reply.json()["Token"]

dev_url = urlunsplit(("https", HOST, "/dna/intent/api/v1/network-device", "", ""))
devices = requests.get(dev_url, headers={"X-Auth-Token": token}, verify=False)

for d in devices.json()["response"]:
    print(d["hostname"], d["managementIpAddress"])

The script gets a token with basic authentication. It then calls the device list with the token in the header, and prints two fields from each device. A Python software development kit exists as well, so you can call functions instead of building URLs.

SD-WAN Manager APIs

SD-WAN Manager has a REST API under the path /dataservice. The Manager documents its calls in an API reference that is available on the Manager itself.

Login uses a session. The client posts a user name and password as form data to /j_security_check, and receives a session cookie. On current releases a second step is needed for calls that change data: the client asks /dataservice/client/token for a token and sends it in a header named X-XSRF-TOKEN.

POST /j_security_check HTTP/1.1
Content-Type: application/x-www-form-urlencoded

j_username=admin&j_password=PASSWORD

Once logged in, the client can read data.

GET /dataservice/device HTTP/1.1
Host: manager.example
Cookie: JSESSIONID=SESSIONVALUE

The reply is JSON with a data key that holds a list of devices, such as controllers and edge routers.

Python and a session

A requests session keeps the cookie for you.

import requests
from urllib.parse import urlunsplit

HOST = "manager.example"
s = requests.Session()
login_url = urlunsplit(("https", HOST, "/j_security_check", "", ""))
s.post(login_url, data={"j_username": "admin", "j_password": "PASSWORD"}, verify=False)

dev_url = urlunsplit(("https", HOST, "/dataservice/device", "", ""))
reply = s.get(dev_url, verify=False)
for d in reply.json()["data"]:
    print(d["host-name"], d["system-ip"])

Comparing the two