Device Level APIs for IOS XE and NX-OS

What it is

Device level APIs are programmable interfaces that run on a single switch or router, so you can manage that box without going through a controller.

Both IOS XE and NX-OS offer them. Beside the traditional CLI and SNMP, they provide model driven interfaces and REST style interfaces.

You need to know which interface each platform offers, how to switch it on, and what each one is good at.

How it works

Each platform has its own set of interfaces, and some of them must be enabled first.

Interfaces on IOS XE

NETCONF and RESTCONF use the YANG data models, which the next page covers.

Enabling NETCONF and RESTCONF on IOS XE

Router(config)# netconf-yang
Router(config)# restconf
Router(config)# ip http secure-server
Router(config)# username admin privilege 15 secret PASSWORD

The netconf-yang command turns on the NETCONF server. The restconf command turns on RESTCONF, and it needs the HTTPS server, which ip http secure-server provides. The account needs the right privilege level.

A RESTCONF request to IOS XE

GET /restconf/data/ietf-interfaces:interfaces HTTP/1.1
Host: ROUTER_ADDRESS
Accept: application/yang-data+json
Authorization: Basic BASE64_OF_USER_AND_PASSWORD

The path starts with /restconf/data/, followed by a module name, a colon and a container name. The media type application/yang-data+json asks for JSON in the YANG data form.

Interfaces on NX-OS

Enabling NX-API

Switch(config)# feature nxapi
Switch# show nxapi

The feature nxapi command turns on the web server for NX-API. show nxapi shows its state and the ports it uses. NX-OS also has a developer sandbox page in the browser, where you can try a command and copy the generated request.

NX-API CLI

NX-API CLI takes ordinary show and configuration commands and returns the result as JSON or XML, so you do not have to parse screen text. Requests go to the /ins path.

{
  "ins_api": {
    "version": "1.0",
    "type": "cli_show",
    "chunk": "0",
    "sid": "1",
    "input": "show version",
    "output_format": "json"
  }
}

The type field says whether the command is a show command or a configuration command. The input field holds the CLI command.

A Python script sends it with requests.

import requests

response = requests.post(
    BASE_URL + "/ins",
    json=payload,
    headers={"content-type": "application/json"},
    auth=("admin", PASSWORD),
    verify=False,
)
print(response.json())

NX-API REST and the object model

NX-API REST exposes the NX-OS data management engine, or DME. Everything on the switch is a managed object in a tree, and you read or change an object by its path.

GET /api/mo/sys/intf/phys-[eth1/1].json

The path /api/mo/ addresses one managed object and /api/class/ queries all objects of a class. Interface names appear in the path in a special bracketed form.

Choosing an interface

• Quick scripts that already use CLI commands: NX-API CLI, or CLI over SSH.
• Structured, model based work on either platform: NETCONF or RESTCONF.
• Streaming telemetry from the device: gNMI or gRPC.
• Logic that must run on the box itself: on box Python.