Getting Started with Cisco MDS 9000 Series NX-API

About NX-API Messages

HTTP Header

A header allows a client and a server to pass extra information as colon separated property-value pairs in requests and responses.

This is where the content encoding is specified for an NX-API request. The supported content types are:

Tag	Description	Type	Values
content-type	Request encoding type.	string	application/json application/json-rpc application/xml

HTTP Method

Cisco MDS NX-API uses the POST method.

Message Body

The message body or payload contains the data for the HTTP method. For a list of supported objects see the NX-API Request Elements section.

Message Response

The message response is an HTTP return code and an HTTP response body that contains the data returned by the method. For a list of supported elements see the NX-API Respone Elements section. For a list of response codes refer to the NX-API Response Codes section.

Configuring the Switch

The Cisco MDS switch must first be configured to enable the NX-API service. For information about how to do this refer to the 'Using NX-API CLI' section in the Cisco MDS 9000 Series NX-OS Programmability Guide.

Accessing Switch Endpoints

Once NX-API is enabled on the switch, it may be accessed using URLs to represent the endpoints for the HTTP communication that transfers the HTTP request. The root endpoint for an NX-API call is the IP address or hostname of the MDS switch.

The Cisco MDS NX-API sandbox is enabled separately and may be accessed through the following endpoints, depending on which transports were enabled on the switch:

HTTPS - https://switch_address:<*port-number*>
HTTP - http://switch_address:<*port-number*>

The Cisco MDS NX-API programmatic interface is enabled when the NX-API feature is enabled on the switch and may be accessed through the following endpoints, depending on which transports were enabled on the switch:

HTTPS - https://switch_address:<*port-number*>/ins
HTTP - http://switch_address:<*port-number*>/ins

Where switch_address is the switch DNS name or IP address and port-number is the port number the service is running on. This port number depends on the NX-API configuration on the switch.

Sample Outputs

To assist with programming with Cisco MDS NX-API, sample outputs are provided in this guide for each command in each of the following formats:

JSON
XML
CLI

A table of possible values that may be returned for each JSON name or XML tag for each command.

Sample Scripts

Sample Python scripts are provided in this guide for each command. To run the sample scripts, you must have Python 3.0 or later installed on the host. The Python imports required by the scripts are from nondefault packages.

To install the "requests" module, use the following command:

python3 -m pip install requests

To install the "json" module, use the following command:

python3 -m pip install json

The sample scripts require various parameters to be supplied before they will work. These are marked with <> in the scripts, where everything including the angle brackets must be replaced. At a minimum, the following parameters are required for each script:

For HTTP: url='http://<*address*>/ins'
For HTTPS: url='https://<*address*>/ins' switchuser='<*user_id*>' switchpassword='<*password*>'

Where: <*address*> is in the format <Switch_Address:Port_Number>. Replace <Switch_Address> with the switch DNS name or IP address and <Port_Number> with the port number of the NX-API service on the switch. <*user_id*> and <password> are the switch user name and password, respectively. Some CLI commands require further parameters, such as module numbers, which are indicated with the same <> syntax in the sample scripts and also must be supplied by the user.

For more information, see the Using NX-API CLI chapter in the Cisco MDS 9000 Series Programmability Guide.

For information on installing SDK for Cisco MDS switches, see the Python SDK/API library for Cisco MDS Switches.

Configuration Commands

To make NX-API requests and response for configuration commands (global configuration mode), add cli_conf type in the payload of the request script and set the send input to the list of commands that you want to enter under that configuration command.

The following example shows how to configure interface FC in global configuration mode (cli_conf) and return its payload output in JSON, JSON-RPC and XML formats.

import requests
import json

"""
Modify these please
"""
url='http://<ip_address>:<port_number>/ins'
switchuser='<user_id>'
switchpassword='<password>'

myheaders={'content-type':'application/json'}
payload={
  "ins_api": {
    "version": "1.2",
    "type": "cli_conf",
    "chunk": "0",
    "sid": "1",
    "input": "interface fc 1/1 ; shutdown",
    "output_format": "json"
  }
}
response = requests.post(url,data=json.dumps(payload), headers=myheaders,auth=(switchuser,switchpassword)).json()
output = json.dumps(response, indent=4, sort_keys=True)
print(output)

{
    "ins_api": {
        "outputs": {
            "output": [
                {
                    "body": {},
                    "code": "200",
                    "input": "interface fc 1/1",
                    "msg": "Success"
                },
                {
                    "body": {},
                    "code": "200",
                    "input": "shutdown",
                    "msg": "Success"
                }
            ]
        },
        "sid": "eoc",
        "type": "cli_conf",
        "version": "1.2"
    }
}

[
    {
        "cmd": "interface fc 1/1",
        "id": 1,
        "jsonrpc": "2.0",
        "result": null
    },
    {
        "cmd": "shutdown",
        "id": 2,
        "jsonrpc": "2.0",
        "result": null
    }
]

    <?xml version="1.0"?>
<ins_api>
  <type>cli_conf</type>
  <version>1.2</version>
  <sid>eoc</sid>
  <outputs>
    <output>
      <body></body>
      <input>interface fc 1/1</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
    <output>
      <body></body>
      <input>shutdown</input>
      <code>200</code>
      <msg>Success</msg>
    </output>
  </outputs>
</ins_api>

Show Commands

To make NX-API requests and response for show commands (Exec mode), add cli_show type in the payload of the request script.

The following example shows how to send request for a show command and return its payload output in JSON and XML formats.

import requests
import json
 
"""
Modify these please
"""
url='http://<ip_address>:<port_number>/ins'
switchuser='<user_id>'
switchpassword='<password>'
 
myheaders={'content-type':'application/json'}
payload={
"ins_api":{
  "version": "1.0",
  "type": "cli_show",
  "chunk": "0",
  "sid": "1",
  "input": "show nxapi",
  "output_format": "json"
  }
} 
response = requests.post(url,data=json.dumps(payload), headers=myheaders,auth=(switchuser,switchpassword)).json()
output = json.dumps(response, indent=4, sort_keys=True)

json_output = json.loads(output)["ins_api"]["outputs"]["output"]["body"]
print(json.dumps(json_output, indent=4, sort_keys=True))

{
    "http_port": 231,
    "https_port": 8443,
    "nxapi_status": "Enabled",
    "sandbox_status": "Disabled",
    "ssl_content": "-----BEGIN CERTIFICATE-----\nMIIDpzCCAo+gAwIBAgIJAPZbKvt6GjebMA0GCSqGSIb3DQEBCwUAMGoxCzAJBgNV\nBAYTAlVTMQswCQYDVQQIDAJDQTERMA8GA1UEBwwIU2FuIEpvc2UxGzAZBgNVBAoM\nEkNpc2NvIFN5c3RlbXMgSW5jLjEPMA0GA1UECwwGZGNueG9zMQ0wCwYDVQQDDARu\neG9zMB4XDTE5MDYyNjE3NTEyOVoXDTE5MDYyNzE3NTEyOVowajELMAkGA1UEBhMC\nVVMxCzAJBgNVBAgMAkNBMREwDwYDVQQHDAhTYW4gSm9zZTEbMBkGA1UECgwSQ2lz\nY28gU3lzdGVtcyBJbmMuMQ8wDQYDVQQLDAZkY254b3MxDTALBgNVBAMMBG54b3Mw\nggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC48Y2jpc2xzUuSy2ij1WD3\nPnuOpkJFe+lkX9z2aGuEpE4JpTOcypnc6pQyHaY01dpGnLBNL2eGC/CAyAK4jXXS\nJSBNSl3PfSuov5ljghYiMI98i+tIixJnRla1INUYFY/eMQCFxpgU9OmzUwhXjLRy\nbNX+OS32kHDSW8176LMnb5kPmnRKrpCUIaqHKaoWgYTW7KqfEHzkHsMyMI66s5Es\n0eiGsZHCYnz0o4z9kdXy1vjzOw2Yj6+2drzsKfWQ3kw4ecB8j56NSqcGwZQThXqN\nQp3bzGvAXII1tUtpWSpnf7Z4xgtG81NxwGdgF8J+VbrmlLDF6SUFpFMigD4gEsOd\nAgMBAAGjUDBOMB0GA1UdDgQWBBTEpi9brvCJoDHcONg02+JLYjcQHjAfBgNVHSME\nGDAWgBTEpi9brvCJoDHcONg02+JLYjcQHjAMBgNVHRMEBTADAQH/MA0GCSqGSIb3\nDQEBCwUAA4IBAQAJFRl/ObQXOelfEQm/DO1BVLy+2dpCdVLOSEh4qo7QAIJGqWUb\nO+M74tMl4nXT245GmJPePQ8TTviODhCGepAke8OpycV2ELlaXTJSs+dg3LnU/8VM\nTsbuW6/6cXxwk8jwbThVx3AHkKnhqlntpT5KigZwC4BuYCxp8YCI/RJRq3KZoZKo\nWHzCsngZNC6G4h8I8KB075JntKMcMudGIZVzm72kSTZvPZ28pV+f0EkjDipV7uv3\ntk9TUIS61ZEk3NngvvSMTdQzNxYMNvxfBzDEAoJm3a7T1u0XSWbky4HEjQmOojYc\nFvS+zu6BMBVF4YqePXxcDRBDBtFg23uJqkZe\n-----END CERTIFICATE-----\n",
    "ssl_enddate": "Jun 27 17:51:29 2019 GMT",
    "ssl_issuer": "C=US, ST=CA, L=San Jose, O=Cisco Systems Inc., OU=dcnxos, CN=nxos"
}

      <nxapi_status>Enabled</nxapi_status>
      <sandbox_status>Disabled</sandbox_status>
      <http_port>231</http_port>
      <https_port>8443</https_port>
      <ssl_issuer>C=US, ST=CA, L=San Jose, O=Cisco Systems Inc., OU=dcnxos, CN=nxos</ssl_issuer>
      <ssl_enddate>Jun 27 17:51:29 2019 GMT</ssl_enddate>
      <ssl_content>-----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIJAPZbKvt6GjebMA0GCSqGSIb3DQEBCwUAMGoxCzAJBgNV
BAYTAlVTMQswCQYDVQQIDAJDQTERMA8GA1UEBwwIU2FuIEpvc2UxGzAZBgNVBAoM
EkNpc2NvIFN5c3RlbXMgSW5jLjEPMA0GA1UECwwGZGNueG9zMQ0wCwYDVQQDDARu
eG9zMB4XDTE5MDYyNjE3NTEyOVoXDTE5MDYyNzE3NTEyOVowajELMAkGA1UEBhMC
VVMxCzAJBgNVBAgMAkNBMREwDwYDVQQHDAhTYW4gSm9zZTEbMBkGA1UECgwSQ2lz
Y28gU3lzdGVtcyBJbmMuMQ8wDQYDVQQLDAZkY254b3MxDTALBgNVBAMMBG54b3Mw
ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC48Y2jpc2xzUuSy2ij1WD3
PnuOpkJFe+lkX9z2aGuEpE4JpTOcypnc6pQyHaY01dpGnLBNL2eGC/CAyAK4jXXS
JSBNSl3PfSuov5ljghYiMI98i+tIixJnRla1INUYFY/eMQCFxpgU9OmzUwhXjLRy
bNX+OS32kHDSW8176LMnb5kPmnRKrpCUIaqHKaoWgYTW7KqfEHzkHsMyMI66s5Es
0eiGsZHCYnz0o4z9kdXy1vjzOw2Yj6+2drzsKfWQ3kw4ecB8j56NSqcGwZQThXqN
Qp3bzGvAXII1tUtpWSpnf7Z4xgtG81NxwGdgF8J+VbrmlLDF6SUFpFMigD4gEsOd
AgMBAAGjUDBOMB0GA1UdDgQWBBTEpi9brvCJoDHcONg02+JLYjcQHjAfBgNVHSME
GDAWgBTEpi9brvCJoDHcONg02+JLYjcQHjAMBgNVHRMEBTADAQH/MA0GCSqGSIb3
DQEBCwUAA4IBAQAJFRl/ObQXOelfEQm/DO1BVLy+2dpCdVLOSEh4qo7QAIJGqWUb
O+M74tMl4nXT245GmJPePQ8TTviODhCGepAke8OpycV2ELlaXTJSs+dg3LnU/8VM
TsbuW6/6cXxwk8jwbThVx3AHkKnhqlntpT5KigZwC4BuYCxp8YCI/RJRq3KZoZKo
WHzCsngZNC6G4h8I8KB075JntKMcMudGIZVzm72kSTZvPZ28pV+f0EkjDipV7uv3
tk9TUIS61ZEk3NngvvSMTdQzNxYMNvxfBzDEAoJm3a7T1u0XSWbky4HEjQmOojYc
FvS+zu6BMBVF4YqePXxcDRBDBtFg23uJqkZe
-----END CERTIFICATE-----
</ssl_content>

The documentation set for the Cisco MDS 9000 Series includes the documents that are listed in this section. To find a document online, access the following URL:

https://www.cisco.com/c/en/us/td/docs/storage/san_switches/mds9000/roadmaps/rel90.html