Programmable APIs and Reading a REST Script

What it is

A programmable API lets software configure and read a device, instead of a person typing commands.

Cisco devices offer several APIs. Some work with data models, and some are plain REST calls. A script is a program that sends requests to one of these APIs, and you must be able to read it and say what it does.

How it works

First the main APIs, then the parts of a REST request, then a worked script.

The main APIs

NETCONF, RESTCONF and gNMI are model driven. They use YANG models to describe the data, so a script can ask for exactly what it needs. The next pages cover each one in detail.

REST basics

REST is an HTTP based style. Each thing you manage is a resource with its own URI, and the HTTP method says what to do. The server keeps no memory between requests, so every request carries its own credentials.

The response has a status code. The common ones are 200 for success, 201 for created, 204 for success with no content, 400 for a bad request, 401 for failed authentication, 403 for no permission, 404 for not found and 409 for a conflict.

Reading a script

When you read a script, find five things: the target, the credentials, the headers, the body and the result handling. This script creates a loopback on an IOS XE device using RESTCONF.

import requests
from urllib.parse import urlunsplit

host = "192.0.2.1"
path = "/restconf/data/Cisco-IOS-XE-native:native/interface"
url = urlunsplit(("https", host, path, "", ""))

headers = {
    "Accept": "application/yang-data+json",
    "Content-Type": "application/yang-data+json",
}

body = {
    "Cisco-IOS-XE-native:Loopback": {
        "name": 100,
        "description": "created by script",
        "ip": {
            "address": {
                "primary": {
                    "address": "10.255.0.1",
                    "mask": "255.255.255.255",
                }
            }
        },
    }
}

response = requests.post(
    url,
    headers=headers,
    json=body,
    auth=("admin", "PASSWORD"),
    verify=False,
)
print(response.status_code)

Read it step by step:

• The URL is built from the host and a RESTCONF path. The path walks down the YANG model, to the interface container.
• The headers say that the request and the response both use JSON in the YANG data format.
• The body names a new Loopback list entry, number 100, with an address and mask.
• requests.post creates the entry, because POST means create.
• auth sends the user name and password, and verify=False turns off certificate checking, which is acceptable only in a lab.
• A status code of 201 means the loopback was created. A 409 would mean it already exists.

The result on the device is the same as typing these commands:

Router(config)# interface Loopback100
Router(config-if)# description created by script
Router(config-if)# ip address 10.255.0.1 255.255.255.255

What to look for in other scripts

Change the method, and the meaning changes. A GET with the same URL and no body would read the interface list.

A PUT or PATCH to a specific entry would replace or change it. A DELETE to that entry would remove it.

Also look for a loop over many devices, which is how automation scales, and for error handling that checks the status code before moving on.