Standard REST methods are supported on the API, which include POST, GET, and DELETE, operations through HTTP.

REST HTTP and HTTPS-Based Methods

The POST and DELETE methods are idempotent, meaning they have no additional effect if they are called more than once with the same input parameters. The GET method is nullipotent, meaning it can be called zero or more times without making any changes (or that it is a read-only operation).

Payload Encapsulation

Payloads to and from the NX-API REST interface can be encoded with either XML or JSON. The XML encoding operation uses the element tag as the name of the package and class, with the respective properties of that object being specified as attributes of the element. Containment is defined by creating child elements.

The following example creates a BGP instance in an XML payload.

Create BGP - XML

Copy  POST https://n9k-sw-1/api/mo/sys/bgp.xml  
  <?xml version="1.0" encoding="UTF-8"?>  
  <bgpEntity adminSt="enabled">  
      <bgpInst adminSt="enabled" asn="65000">  
      </bgpInst>  
  </bgpEntity>

JSON encoding requires definition of certain entities to reflect the tree-based hierarchy.

• All objects are described as JSON dictionaries. The key is the name of the package and class while the value is another nested dictionary with two keys: attribute and children.
• The attribute key contains a further nested dictionary describing key-value pairs that define attributes on the object.
• The children key contains a list that defines all the child objects. The children in this list are dictionaries containing any nested objects which are defined as described in the MIT.

The following example creates a BGP instance in a JSON payload.

Create BGP Peer - JSON

Copy  POST https://n9k-sw-1/api/mo/sys/bgp/inst/dom-default.json  
  {  
      "bgpPeer": {  
          "attributes": {  
              "addr": "192.168.0.2",  
              "asn": "65000"  
          }  
      }  
  }  

Both examples have been abbreviated to simplify visual understanding.

Read Operations

After the object payloads are properly encoded as XML or JSON, they can be used in create, read, update, or delete (CRUD) operations through the REST API.

Read Operations

Copy   GET https://n9k-sw-1/api/mo/sys/bgp.json  

Response to the above query:

Copy  {  
      "totalCount": "1",  
      "imdata": [  
          {  
              "bgpEntity": {  
                  "attributes": {  
                      "adminSt": "enabled",  
                      "childAction": "",  
                      "dn": "sys/bgp",  
                      "lcOwn": "local",  
                      "modTs": "2015-09-30T03:28:52.083+00:00",  
                      "monPolDn": "uni/fabric/monfab-default",  
                      "name": "",  
                      "operErr": "",  
                      "operSt": "enabled",  
                      "status": ""  
                  }  
              }  
          }  
      ]  
  }  

Because NX-API REST uses HTTP, defining the universal resource identifier (URI) to access a certain resource type is important. The first two sections of the request URI simply define the protocol and access details (hostname, IP address) of a Cisco Open NX-OS device. Next in the request URI is the literal string "/api", followed by the DN of the object or class being queried. The final part of the request URI is the encoding format: JSON or XML.

The optional part of a request URI consists of any query options. Query options provide filtering capabilities to developers, and are explained extensively in the NX API REST documentation available at https://developer.cisco.com/site/nx-os.

Copy  GET https://n9k-sw-1/api/class/l1PhysIf.json  

Response to the above query:

Copy  {  
      "totalCount": "54",  
      "imdata": [  
          {  
              "l1PhysIf": {  
                  "attributes": {  
                      "accessVlan": "vlan-1",  
                      "adminSt": "up",  
                      "autoNeg": "on",  
                      "descr": "",  
                      "dn": "sys/phys-[eth1/33]",  
                      "dot1qEtherType": "0x8100",  
                      "duplex": "auto",  
                      "ethpmCfgFailedBmp": "",  
                      "ethpmCfgFailedTs": "00:00:00:00.000",  
                      "ethpmCfgState": "0",  
                      "id": "eth1/33",  
                      "inhBw": "unspecified",  
                      "layer": "Layer2",  
                      "linkDebounce": "100",  
                      "linkLog": "default",  
                      "modTs": "2015-06-26T16:04:10.748+00:00",  
                      "mode": "access",  
                      "monPolDn": "uni/infra/moninfra-default",  
                      "mtu": "1500",  
                      "name": "",  
                      "speed": "auto",  
                      "trunkVlans": "",  
                  }  
              }  
          },  
          {  
              ...  
          }  
      }  
    ]  
  }    

The example above shows a query for all objects with class "l1PhysIf". For a complete reference to the various objects and their properties and possible values, refer to the Cisco NX-API REST documentation at https://developer.cisco.com/site/nx-api/documents/apis/n3k-n9k-api-ref.

Write Operations

Create and update operations in the REST API are implemented using the POST method, so if an object does not already exist, it will be created. If the object already exists, it will be updated to reflect any changes between its existing state and desired state.

Both create and update operations can contain complex object hierarchies. A complete tree can be defined in a single command as long as all objects are within the same context and root, and are under the 1MB limit for the REST API data payloads. This limit is in place to guarantee performance and protect the system under high load. Very large operations may need to be broken into smaller pieces.

Write Operations

Copy  POST https://n9k-sw-1/api/mo/sys/bgp/inst/dom-default.json  
  {  
      "bgpPeer": {  
          "attributes": {  
              "addr": "192.168.0.2",  
              "asn": "65000"  
          }  
      }  
  }    

Create and update operations use the same syntax as read operations, except they are always executed at an object level, as you cannot make changes to every object of a specific class. The create or update operation should target a specific managed object; the literal string "/mo" in a URL indicates the DN of the managed object will be provided, followed by the DN. Filter strings can be applied to POST operations. As an example, if you want to retrieve the results of your POST operation in the response, you can pass the rsp‑subtree=modified query string to indicate you want the response to include any objects that have been modified by the POST operation.

The payload of the POST operation will contain the XML or JSON encoded data representing the managed object being queried.

In summary, REST-based APIs are the most popular APIs today. They are easy to use, well documented and language independent. NX-API REST exposes these benefits while presenting a comprehensive data model for managing network infrastructures.