Cisco Nexus Switches:
Programmability with NX-API
White Paper
Cisco Nexus Switches:
Programmability with NX-API
© 2016 Cisco and/or its affiliates. All rights reserved.
Cisco Nexus Switches:
Programmability with NX-API
White Paper
Table of Contents
What You Will Learn
page
3
Introduction3
Security3
Cisco NX-OS APIs
4
Using the NX-API CLI
4
Using the NX-API Sandbox
5
Cisco NX-API Request and Response
6
Cisco Proprietary Request and Response
7
Conclusion11
For More Information
© 2016 Cisco and/or its affiliates. All rights reserved.
11
Cisco Nexus Switches:
Programmability with NX-API
White Paper
What You Will Learn
In this document, you will learn how the Cisco Nexus® switches align with business
and IT needs to integrate programmability and automation into the entire network
infrastructure. Automation has always been an important part of administration, but it is
even more important now as networks become more robust. Automation is essential
in a massively scalable data center (MSDC), which may add hundreds of nodes in
a week. To support this trend, Cisco has added new features to the Cisco Nexus
switches while at the same time reducing complexity, cost, and training overhead.
One of these new features is Cisco® NX-API, which provides a programmatic interface
for Cisco Nexus switches using HTTP/HTTPS as the transport mechanism.
Introduction
Security
On Cisco Nexus devices, command-line interfaces
(CLIs) are run only on the device. NX-API improves
the accessibility of these CLIs by making them
available outside the switch with HTTP/HTTPS.
You can use this extension to the existing Cisco
Nexus CLI on Cisco Nexus devices. NX-API
supports show commands, action and execution
commands, configuration commands, and Linux
Bash commands.
The switch and all user data remain secure
throughout the use of NX-API. Before running any
CLI command, user-level credentials are verified
to help ensure that the specified username and
password are valid. NX-API also verifies that the
specified user has the required permissions to
perform the requested CLI command prior to
taking any action. If additional security is needed,
secure and encrypted access to the switch can be
achieved through HTTPS.
NX-API uses HTTP/HTTPS as its transport
mechanism. CLIs are encoded into the HTTP/HTTPS
POST body. The NX-API back end uses the NGINX
HTTP server.
© 2016 Cisco and/or its affiliates. All rights reserved.
NX-API uses HTTP basic authentication. HTTP/
HTTPS requests must contain the username and
password in the HTTP header. NX-API provides a
session-based cookie using the name nxapi_auth
for authenticated users when users first successfully
authenticate. That session cookie should be
included in subsequent NX-API requests.
Cisco Nexus Switches:
Programmability with NX-API
White Paper
Cisco NX-OS APIs
Using the NX-API CLI
The Cisco NX-OS APIs provided by NX-API on Cisco
Nexus switches allows web-based programmatic
access to Cisco Nexus devices. This support is
delivered through an open-source web server,
NGINX. NX-API exposes the complete configuration
and management capabilities of the CLI through
web-based APIs. The Cisco Nexus switches can
be instructed to publish the output of the API calls
in either XML or JavaScript Object Notation (JSON)
format. This comprehensive, easy-to-use API allows
rapid deployment on Cisco Nexus switches (Figure
1). You can access several scripts on the GitHub site
that have already been configured for you. Go to
https://github.com/datacenter/nxos/tree/master/nxapi
to find these scripts, and more are constantly being
added.
The commands, command type, and output type
for Cisco Nexus devices are entered using NXAPI by encoding the commands in the body of a
HTTP/HTTPS POST request. The response to the
request is returned in XML or JSON output format.
You must enable NX-API with the feature manager
CLI command on the device. By default, NX-API
is disabled. The following example shows how to
enable NX-API:
1.Enable the management interface.
switch# conf t
switch(config)# interface mgmt 0
switch(config)# ip address
198.51.100.1/24
switch(config)# vrf context
management
switch(config)# ip route
203.0.113.1/0 1.2.3.1
2.Enable the NX-API feature.
switch# conf t
switch(config)# feature nxapi
Figure 1. Programmatic Access to Cisco Nexus through Cisco NX-API
NGINX
CLI Input
Cisco Nexus
© 2016 Cisco and/or its affiliates. All rights reserved.
HTTP and HTTPs
Programmability
Cisco Nexus Switches:
Programmability with NX-API
White Paper
Using the NX-API Sandbox
The NX-API sandbox is the web-based user
interface that you can use to enter the commands,
command type, and output type for Cisco Nexus
devices using HTTP/HTTPS. After you post the
request, the output response is displayed. By default,
the NX-API sandbox is disabled.
Begin by enabling NX-API with the feature manager
CLI command on the switch. Then enable the
sandbox web user interface with the nxapi sandbox
command. Use a browser to access the NX-API
sandbox. The following example shows how to
configure and launch the NX-API sandbox:
1.Enable the management interface.
switch# conf t
switch(config)# interface mgmt 0
switch(config)# ip address
198.51.100.1/24
switch(config)# vrf context
management
switch(config)# ip route
203.0.113.1/0 1.2.3.1
2.Enable the NX-API nxapi feature.
switch# conf t
switch(config)# feature nxapi
switch(config)# nxapi sandbox
3.Open a browser and enter http://mgmt-ip to
launch the NX-API sandbox. Figure 2 shows an
example of a request and the response.
Figure 2. Programmatic Access to Cisco Nexus through Cisco NX-API
In the NX-API sandbox, you specify the commands, command type, and output type in the top pane. Click
the POST button to post the request. Brief descriptions of the request elements are displayed in the left
pane. After the request is posted, the output response is displayed in the right pane. When you use the NXAPI sandbox, Cisco recommends that you use the Firefox Release 24.0 or later as your browser.
© 2016 Cisco and/or its affiliates. All rights reserved.
Cisco Nexus Switches:
Programmability with NX-API
White Paper
Cisco NX-API Request and Response
The NX-API request can be encoded in the standard JSON-RPC 2.0 format or in Cisco’s proprietary JSON
and XML format, as shown here.
JSON RPC Request and Response
The fields shown in Table 1 must be present for a valid JSON-RPC 2.0 request.
Table 1. Required Fields in a JSON-RPC 2.0 Request
Field
Description
jsonrpc
A string specifying the version of the JSON-RPC protocol. This string must be
exactly 2.0.
method
A string containing the name of the method to be invoked. NX-API supports
either:
● cli: Show or configuration commands
● cli _ ascii: Show or configuration commands output without formatting
params
A structured value that holds the parameter values to be used during the invocation of the method. It must contain the following fields:
● cmd: A CLI command
● version: NX-API request version identifier
id
An optional identifier established by the client that must contain a string,
number, or null value if it is specified. The value should normally not be null,
and numbers should not contain fractional parts. If the user does not specify
the id parameter, then the server assumes that the request is simply a notification, and no response will be given.
The JSON-RPC response will contain the fields shown in Table 2.
Table 2. Fields in a JSON-RPC Response
Field
Description
jsonrpc
A string specifying the version of the JSON-RPC protocol. The string will be
exactly 2.0.
result
This field is included only on success. The value of this field contains the
requested CLI output.
error
This field is included only on an error (it is mutually exclusive with the result object). The error object contains the following fields:
● code: An integer error code as specified by the JSON-RPC specification
● message: A human-readable string that corresponds with the error code
●
data: An optional structure that can contain any other information useful to
the user (such as CLI error output or additional information if available)
id
This field will have the same value as the id field in the corresponding request
object. If a problem occurred in parsing the id field in the request, this
value will be null.
© 2016 Cisco and/or its affiliates. All rights reserved.
Cisco Nexus Switches:
Programmability with NX-API
White Paper
The following example shows a request and its response in JSON RPC format:
{
“JSONRPC”: “2.0”,
“method”: “cli”,
“params”: {
“cmd”: “show hostname”,
“version”: 1
},
“id”: “1”
}
{
“jsonrpc”: “2.0”,
“result”: {
“body”: {
“hostname”: “switch”
}
},
“id”: 1
}
Cisco Proprietary Request and Response
NX-API also has a format that is proprietary to Cisco. Both XML and JSON structures are supported for this
format. Request objects in either XML or JSON can contain the fields shown in Table 3.
© 2016 Cisco and/or its affiliates. All rights reserved.
Cisco Nexus Switches:
Programmability with NX-API
White Paper
Table 3. Fields in a Cisco Proprietary Request
Field
Description
version
Indicates the current NX-API version.
type
A string containing the type of command to be run. The current choices are:
●
cli _ show: Show commands. If the command does not support XML output, an
error message will be returned.
● cli _ show _ ascii: Show commands output without formatting.
●
cli _ conf: Configuration commands. Interactive configuration commands are
not supported.
● bash: Bash commands. Most noninteractive Bash commands are supported. Note
that Bash commands should be run on switches with the Bash shell enabled.
chunk
To handle a large amount of show command output, NX-API supports output
chunking for show commands. 0 means no chunk output and 1 means chunk output. If this field is specified in the request, the user will receive the response in multiple chunks.
sid
Valid when the response message is chunked. To retrieve the next chunk of message, the user is expected to send a NX-API request with sid set to the sid in
the previous response message.
input
The input can be one or multiple commands. Commands belonging to different
types should not be mixed. Multiple commands should be separated with “;” (that
is, a blank character followed by a semicolon) for message types of cli _ show,
cli _ show _ ascii, and cli _ conf. For bash commands, “;” (without a blank character) should be used.
output _
format
The expected output message format. The value can be either xml or json.
The Cisco proprietary response for both XML and JSON requests will contain the fields listed in Table 4.
Table 4. Fields in Cisco Proprietary Responses
Field
Description
version
Indicates the current NX-API version.
type
Indicates the type of command being run.
sid
Session ID of current response. This field is valid only for chunked output.
outputs
Tag enclosing the output of all the commands.
output
Tag enclosing the output of a single command. For cli _ conf and bash, it
contains the output of all the commands.
body
The body of the response to the command.
code
The error code of the command processing. Standard HTTP error codes are
used here.
msg
The error message associated with the error code, providing more details of
the command processing status.
© 2016 Cisco and/or its affiliates. All rights reserved.
Cisco Nexus Switches:
Programmability with NX-API
White Paper
The following example shows a request and its response in XML format.
Request
#!/usr/bin/python
import requests
import json
url=’http://10.196.98.66/ins’
switchuser=’admin’
switchpassword=’Cisc0123’
myheaders={‘content-type’:’application/xml’}
payload=”””<?xml version=”1.0”?>
<ins_api>
<version>0.1</version>
<type>cli_show</type>
<chunk>0</chunk>
<sid>session1</sid>
<input>show switchname</input>
<output_format>xml</output_format>
</ins_api> “””
response = requests.post(url,data=payload,
headers=myheaders,auth=(switchuser,switchpassword))
print response.text
Response
<?xml version=”1.0”?>
<ins_api>
<type>cli_show</type>
<version>0.1</version>
<sid>eoc</sid>
<outputs>
<output>
<body>
<hostname>switch</hostname>
© 2016 Cisco and/or its affiliates. All rights reserved.
Cisco Nexus Switches:
Programmability with NX-API
White Paper
</body>
<input>show switchname</input>
<msg>Success</msg>
<code>200</code>
</output>
</outputs>
</ins_api>
The following example shows a request and its response in JSON format.
Request
#!/usr/bin/python
import requests
import json
url=’http://10.196.98.66/ins’
switchuser=’admin’
switchpassword=’Cisc0123’
myheaders={‘content-type’:’application/json’}
payload=
{
“ins_api”: {
“version”: “0.1”,
“type”: “cli_show”,
“chunk”: “0”,
“sid”: “session1”,
“input”: “show switchname”,
“output_format”: “json”
}
}
response = requests.post(url,data=json.dumps(payload),
headers=myheaders,auth=(switchuser,switchpassword))
print response.content
© 2016 Cisco and/or its affiliates. All rights reserved.
Cisco Nexus Switches:
Programmability with NX-API
White Paper
Response
{
“ins_api”: {
“type”: “cli_show”,
“version”: “0.1”,
“sid”: “eoc”,
“outputs”: {
“output”: {
“body”: {
“hostname”: “switch”
},
“input”: “show switchname”,
“msg”: “Success”,
“code”: “200”
}
}
}
}
Conclusion
Cisco is a leader in data center automation and orchestration with the Cisco Nexus Family switches. By
embracing the open approach of DevOps and creating a more Linux-like environment in the Cisco Nexus
Family, Cisco enables IT departments with strong Linux skill sets to meet business needs efficiently. In addition,
by supporting orchestration tools such as Ansible within the shell or Linux container (LXC) and Cisco NX-API,
Cisco Nexus enables customers to use the same orchestration tools that are used on servers to configure
switches in a touchless manner, thereby reducing the potential for human error and accelerating processes.
For More Information
For more information about Cisco NX-API, visit https://developer.cisco.com/site/nx-api/.
Prepared By
Shashi Bansal
Nikhita Kataria
Last Updated: March 2016
© 2016 Cisco and/or its affiliates. All rights reserved. Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S.
and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of
their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)
C11-736861-00 03/16