My Personal Notes on NX-API

Day 0 provisioning: Zero-touch device provisioning has been available on network devices for years.

POAP was designed to provide advanced Day 0 provisioning capabilities using an extensible framework. POAP includes the ability to execute Python scripts as part of its workflow.

Today, POAP can download and install additional management agents and apply specific configurations that are based on information such as location in a network topology.

A similar approach is achieved by using Preboot Execution Environment (PXE). PXE has extended its presence into the network as infrastructure devices are increasingly managed more like servers. Cisco NX-OS uses iPXE, which utilizes an open source network firmware that is based on gPXE/Etherboot.

• traditional SNMP support
• The Python interpreter
• Python scripting capability on devices to provide programmatic access to the switch CLI to perform various tasks including:
  • POAP actions
  • EEM actions.

• built-in web server to repond to HTTP calls
• NETCONF
• NX-API
• CLI

• Cisco Nexus switches* based upon a Linux foundation from day 1 and so have:
  • native Linux Bourne Again Shell (Bash), but today
  • Linux guest shell which is a separate Linux environment running on the switch inside a container, utilizing a CentOS distribution,
  • guest shell has the ability to securely run third-party applications that monitor and control the switch.

Cisco NX-OS incorporates a set of tools, features, and capabilities that enable automation. Modern configuration management tools like:

• Puppet,
• Chef, and
• Ansible

to drive programmability.

• ~feaeture nx-api ~
• feaeture bash-shell
• feaeture netconf
• feaeture restconf
• feaeture grpc
• feaeture interface vlan # %%
• feaeture nx-api

  %% this enables SVIs which are good when you are learning and you don't actually have a real switch. (can be used on a real switch too of course..)

standard protocol for procedure call support (lightweight) can run over HTTP, but is NOT a REST API. defines the REQUEST and RESONSE format only for sending communication from one device to another. _Can send CLI commands_.

Request:

[
  {
    "jsonrpc": "2.0",
    "method": "cli",
    "params": {
      "cmd": "show ip int brief vrf management",
      "version": 1
      },
    "id": 1
   }
 ]

This example had "method": "cli" which returns nice structured data, jsonrpc data. This format is the easiest way for programs to consume it. The other option is "cli-ascii" which would return a more traditional, human readable cli output, as one raw string. Some older "screen scraping" scripts may want this type of output.

Response

{
  "jsonrpc": "2.0",
  "result": {
   "body": {
    "TABLE_intf": {
     "ROW_intf": {
      "intf-name": "mgmt0",
      "prefix": "10.10.20.58",
      "ip-disabled": "FALSE",
      "iod": 2,
      "proto-state": "up",
      "link-state": "up",
      "admin-state": "up"
      }
     }
    }
   }
   "id": 1
  }

Alternative CLI based API, that provides distinct "show" and "config" methods. Because this was developed by and for Cisco, it provides somewhat enhanced output, better error messages with better data than the standards based JSON-RPC. Features:

• send "show" and "config" commands
• send bash commands directly to your router, not just cli commands,
• supports either format:
  • XML
  • JSON

    Requst:

{
  "ins_api": {
   "version": "1.0",
   "type": "cli_show",
   "chunk": "0",
   "sid", "1",
   "input": "show ip int brief vrf management",
   "output_format": "json"
   }
 }

Now, very much like json above;

This example had "type": "cli_show" which returns nice structured data, jsonrpc data. This format is the easiest way for programs to consume it. The other option is "cli_show_ascii" which would return a more traditional, human readable cli output, as one raw string. Some older "screen scraping" scripts may want this type of output.

Zintis, don't use this, because you'd be back at parsing the output to get it into a python format, such as a dictionary. Best to just stick to cli_show type, as that will return proper json formatted responses that with which you can utilized standard library json.read modules to ingest that data into a python object.

Note, that INS_API also gives 2 more modes, one is "cli_conf" It is used for sending configuration. Show commands also would work.

The last is bash, which is good for sending underlying bash commands to the switch. This mode would require you to enable bash mode on the switch ahead of time, with feature bash

Response:

{"ins_api": {
  "type": "cli_show", "version": "10",
    "sid": "eoc",
  "outputs":{
   "output":{
    "input": "show ipo int brief vrf management",
    "msg": "Success",
    "code": "200",
    "body": {
      TABLE_intf": {
       "ROW_intf": {
	"int-name": "mgmt0",
	"prefix": "10.10.20.58",
	"proto-state": "up",
	"link-state": "up",
	"admin-state": "up"
	}}
      "TABLE_vrf": {  
       "ROW_vrf": {
	"vrf-name-out": "management"
}}}}}}}

This is a full REST API with access to the underlying data model. It runs NOT as a simple programming interface to the CLI, but as a true API that works with the yang data model itself

That is why you don't get many functioning CLI outputs when using the NX-API developer sandbox to try CLI commands. (remember that is just browsing to the switch, and not visore)

• RPC-style web API
• enable programmatic access to Nexus devices
• improves accessibility of the CLI by making them available off-box
• supports show commands, configurations, and Linux Bash.

NX-API improves the accessibility of these CLIs by making them available outside of the switch by using HTTP and HTTPS. You can use the NX-API as an extension to the existing Cisco Nexus CLI. The NX-API CLI API is great for network engineers getting started with the API because it still makes use of commands. It sends commands to the device, wrapped in HTTP and HTTPS, but receives structured data back. You have the ability to send

• show commands
• config commands
• Linux commands

directly to the switches using the NX-API CLI

• Runs on HTTP and HTTPS transport
• CLI commands are encoded into the HTTP/HTTPS POST body
• The request/response format is encoded with JSON-RPC, JSON, or XML
• NGINX HTTP back-end web server to listen for HTTP requests

NX-API CLI example

{
  "jsonrpc": "2.0",
  "method": "cli",
  "params": {
    "cmd": "show hostname",
    "version": 1
  },
  "id": 1
}

Matching response

{
  "jsonrpc": "2.0",
  "result": {
    "body": {
      "hostname": “n9k2.cisco.com"
    }
  },
  "id": 1
}

The NGINX runs in a cgroup, so has full protection from processes on the switch, and vice-versa.

First off, it is for Nexus 3K and Nexus 9K (others don't yet have the RESTful API ) Also, realize that this is NOT for CLI, but rather for direct interactions with the underlying switch object models. Don't expect "show ip int brief" here.

Everything in REST API lives in a tree. the root of the tree is called SYS Use Visore to explore that.

NX-API-REST was built to mimick the Cisco ACI construct. That is why you don't see "vlan" objects but they are called "layer 2 bridge domain" l2BD

NX-API REST uses a ticket (token) for authenticting API call. For us to use NX-API REST, we will have to first "login in". We still login using a Postman post, but we do that do the equivalent of a login page. That is:

POST to /api/aaaLogin.json with credentials to receive token. i.e. you will have to include a username and password to this post.

This is done only once, with the purpose of us getting a token, so that subsequent requests can use the token and in a way bypass the authentication

POST /api/aaaLogin.json

Make this your PostMan body:

{
    "aaaUser": {
      "attributes": {
	    "name": "{{username}}",
	    "pwd": "{{password}}"
	    }
    }
}

Please note that the {{ }} are Postman's variables. These variables are set through the upper right environment settings. They are saved in collections too.

SEND this via postman and get the reponse, which should include 200 OK and a token.

Once we get the response we could copy that token and save it into our programs, but with Postman don't have to do that. That is because once logged in Postman will automatically include the token in subsequent requests as a session cookie.

• nice of Postman.

Actually to be more accurate, after the initial response that includes the token, Postman uses session cookies in subsequent exchanges, not the token everytime. Still automatic though. (peek under the cookies tab in the return maybe…. )

This is how you can use two tools together, VISORE and POSTMAN

From youtube, with an interview with Hank Preston here on youtube

It is the method that will dictate if you are reading information (GET) or updating/writing information (PUT or POST)