Coding Tasks with Platform APIs

What it is

A coding task gives you a goal and a piece of API reference, and you write the calls that reach the goal.

The outline lists three families: get a list of network devices, manage Webex spaces, participants and messages, and list the clients seen on a network. All follow the same pattern: authenticate, call an endpoint, read the JSON.

Every endpoint here is shown as a path. Your code adds the base address that the platform documents.

How it works

Start with how the platform authenticates, then choose the endpoint, then read the fields.

Meraki devices and clients

Authentication is the API key in a header. Devices belong to networks, which belong to an organisation.

import requests

headers = {"X-Cisco-Meraki-API-Key": API_KEY}

orgs = requests.get(BASE_URL + "/organizations", headers=headers).json()
org_id = orgs[0]["id"]

nets = requests.get(
    BASE_URL + "/organizations/" + org_id + "/networks", headers=headers
).json()
net_id = nets[0]["id"]

devices = requests.get(
    BASE_URL + "/networks/" + net_id + "/devices", headers=headers
).json()
clients = requests.get(
    BASE_URL + "/networks/" + net_id + "/clients",
    headers=headers,
    params={"timespan": 86400},
).json()

The reply is a JSON list. Each device has fields such as name, model and serial.

Each client has fields such as description, ip and mac. The timespan is in seconds.

Catalyst Center devices and hosts

First get a token, then send it in X-Auth-Token.

auth = requests.post(
    BASE_URL + "/dna/system/api/v1/auth/token", auth=("admin", PASSWORD)
)
headers = {"X-Auth-Token": auth.json()["Token"]}

devices = requests.get(
    BASE_URL + "/dna/intent/api/v1/network-device", headers=headers
).json()["response"]
for d in devices:
    print(d["hostname"], d["managementIpAddress"])

The list sits under the response key. For clients and hosts, Catalyst Center has lookups in the same Intent API. The exact path, filters and field names depend on the release, so read them from the documentation and then repeat the same pattern: send the token header and loop over response.

ACI devices

The APIC uses a login call with a JSON body. It then keeps the session in a cookie, so a requests.Session is handy.

session = requests.Session()
login = {"aaaUser": {"attributes": {"name": "admin", "pwd": PASSWORD}}}
session.post(BASE_URL + "/api/aaaLogin.json", json=login)

reply = session.get(BASE_URL + "/api/node/class/fabricNode.json").json()
for item in reply["imdata"]:
    attrs = item["fabricNode"]["attributes"]
    print(attrs["name"], attrs["role"])

The objects come back under imdata. Each one is wrapped in its class name, and the data sits under attributes.

SD-WAN devices

The manager uses a session login and then an extra token header.

session = requests.Session()
session.post(
    BASE_URL + "/j_security_check",
    data={"j_username": "admin", "j_password": PASSWORD},
)
token = session.get(BASE_URL + "/dataservice/client/token").text
session.headers["X-XSRF-TOKEN"] = token

devices = session.get(BASE_URL + "/dataservice/device").json()["data"]
for d in devices:
    print(d["host-name"], d["system-ip"])

Login uses form data, so the script uses data= and not json=. Newer releases can also use other login methods, so follow the manager's documentation.

NSO devices

NSO exposes its device list through RESTCONF, with basic authentication.

headers = {"Accept": "application/yang-data+json"}
reply = requests.get(
    BASE_URL + "/restconf/data/tailf-ncs:devices/device",
    headers=headers,
    auth=("admin", PASSWORD),
).json()
for d in reply["tailf-ncs:device"]:
    print(d["name"], d["address"])

Webex spaces, participants and messages

Webex uses a bearer token. The API calls spaces rooms and participants memberships.

headers = {"Authorization": "Bearer " + TOKEN}

room = requests.post(
    BASE_URL + "/v1/rooms", headers=headers, json={"title": "Ops"}
).json()

requests.post(
    BASE_URL + "/v1/memberships",
    headers=headers,
    json={"roomId": room["id"], "personEmail": PERSON_EMAIL},
)

requests.post(
    BASE_URL + "/v1/messages",
    headers=headers,
    json={"roomId": room["id"], "text": "Maintenance at 22:00"},
)

members = requests.get(
    BASE_URL + "/v1/memberships",
    headers=headers,
    params={"roomId": room["id"]},
).json()["items"]

Lists come back under the items key. A GET on /v1/rooms lists spaces, and a GET on /v1/messages with a roomId lists messages.

Spotting the pattern