Scribd
Upload
40 views

NX Api-1

The document discusses NX-API which allows CLI access to Cisco Nexus devices from outside the switch using HTTP/HTTPS. It supports show commands, configurations and JSON-RPC. Security is provided by HTTPS and user authentication. Examples are provided for making API calls and obtaining response data in XML or JSON format.

Uploaded by

billthuso
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
40 views

NX Api-1

The document discusses NX-API which allows CLI access to Cisco Nexus devices from outside the switch using HTTP/HTTPS. It supports show commands, configurations and JSON-RPC. Security is provided by HTTPS and user authentication. Examples are provided for making API calls and obtaining response data in XML or JSON format.

Uploaded by

billthuso
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 12

NX-API

• About NX-API, page 1


• Using NX-API, page 2
• Additional References, page 10

About NX-API
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 of the switch by using HTTP/HTTPS. You can
use this extension to the existing Cisco Nexus CLI system on the Cisco Nexus 5000 and 6000 Series devices.
NX-API supports show commands and configurations.
NX-API supports JSON-RPC.

Transport
NX-API uses HTTP/HTTPS as its transport. CLIs are encoded into the HTTP/HTTPS POST body.
The NX-API backend uses the Nginx HTTP server. The Nginx process, and all of its children processes, are
under Linux cgroup protection where the CPU and memory usage is capped. If the Nginx memory usage
exceeds the cgroup limitations, the Nginx process is restarted and restored.

Message Format
NX-API is an enhancement to the Cisco Nexus 5000 and 6000 Series CLI system, which supports XML
output. NX-API also supports JSON output format for specific commands.

Note • NX-API XML output presents information in a user-friendly format.


• NX-API XML does not map directly to the Cisco NX-OS NETCONF implementation.
• NX-API XML output can be converted into JSON.

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


1
NX-API
Security

Security
NX-API supports HTTPS. All communication to the device is encrypted when you use HTTPS.
NX-API is integrated into the authentication system on the device. Users must have appropriate accounts to
access the device through NX-API. NX-API uses HTTP basic authentication. All requests must contain the
username and password in the HTTP header.

Note You should consider using HTTPS to secure your user's login credentials.

You can enable NX-API by using the feature manager CLI command. NX-API is disabled by default.
NX-API provides a session-based cookie, nxapi_auth when users first successfully authenticate. With the
session cookie, the username and password are included in all subsequent NX-API requests that are sent to
the device. The username and password are used with the session cookie to bypass performing the full
authentication process again. If the session cookie is not included with subsequent requests, another session
cookie is required and is provided by the authentication process. Avoiding unnecessary use of the authentication
process helps to reduce the workload on the device.

Note A nxapi_auth cookie expires in 600 seconds (10 minutes). This value is a fixed and cannot be adjusted.

Note NX-API performs authentication through a programmable authentication module (PAM) on the switch.
Use cookies to reduce the number of PAM authentications, which reduces the load on the PAM.

Using NX-API
The commands, command type, and output type for the Cisco Nexus 5000 and 6000 Series devices are entered
using NX-API by encoding the CLIs into the body of a HTTP/HTTPs POST. 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:
• Enable the management interface.
switch# configure terminal
switch(config)# interface mgmt 0
switch(config)# ip address 198.51.100.1/24
switch(config)# vrf context managment
switch(config)# ip route 203.0.113.1/0 1.2.3.1

• Enable the NX-API nxapi feature.


switch# configure terminal
switch(config)# feature nxapi

The following example shows a request and its response in XML format:

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


2
NX-API
Using NX-API

Request:
<?xml version="1.0" encoding="ISO-8859-1"?>
<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:
<?xml version="1.0"?>
<ins_api>
<type>cli_show</type>
<version>0.1</version>
<sid>eoc</sid>
<outputs>
<output>
<body>
<hostname>switch</hostname>
</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:
{
"ins_api": {
"version": "0.1",
"type": "cli_show",
"chunk": "0",
"sid": "session1",
"input": "show switchname",
"output_format": "json"
}
}

Response:
{
"ins_api": {
"type": "cli_show",
"version": "0.1",
"sid": "eoc",
"outputs": {
"output": {
"body": {
"hostname": "switch"
},
"input": "show switchname",
"msg": "Success",
"code": "200"
}
}
}
}

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


3
NX-API
Sample NX-API Scripts

Sample NX-API Scripts


The sample scripts demonstrate how a script is used with NX-API. The scripts are available at
https://github.com/datacenter/nxos/tree/master/nxapi/samples.
• Cable Checker (check_cable.py)
• Cable Checker Blueprint (connectivity.json)

Obtaining the XSD Files

Step 1 From your browser, navigate to the Cisco software download site at the following URL:
http://software.cisco.com/download/navigator.html
The Download Software page opens.

Step 2 In the Select a Product list, choose Switches > Data Center Switches > platform > model .
Step 3 If you are not already logged in as a registered Cisco user, you are prompted to log in now.
Step 4 From the Select a Software Type list, choose NX-OS XML Schema Definition.
Step 5 Find the desired release and click Download.
Step 6 If you are requested, follow the instructions to apply for eligibility to download strong encryption software images.
The Cisco End User License Agreement opens.

Step 7 Click Agree and follow the instructions to download the file to your PC.

NX-API Sandbox
The NX-API Sandbox is the web-based user interface that you use to enter the commands, command type,
and output type for the Cisco Nexus 5000 and 6000 Series device using HTTP/HTTPS. After posting the
request, the output response is displayed.
By default, NX-API is disabled. Begin enabling NX-API with the feature manager CLI command on the
switch. Then enable NX-API with the nxapi sandbox command.
Use a browser to access the NX-API Sandbox.

Note When using the NX-API Sandbox, Cisco recommends that you use the Firefox browser, release 24.0 or
later.

The following example shows how to configure and launch the NX-API Sandbox:
• Enable the management interface.
switch# conf t
switch(config)# interface mgmt 0
switch(config)# ip address 198.51.100.1/24

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


4
NX-API
NX-API Sandbox

switch(config)# vrf context managment


switch(config)# ip route 203.0.113.1/0 1.2.3.1

• Enable the NX-API nxapi feature.


switch# conf t
switch(config)# feature nxapi
switch(config)# nxapi sandbox

• Open a browser and enter http://mgmt-ip to launch the NX-API Sandbox. The following figure is an
example of a request and output response.

Figure 1: NX-API Sandbox with Example Request and Output Response

In the NX-API Sandbox, you specify the commands, command type, and output type in the top pane. Click
the POST Request button above the left pane to post the request. Brief descriptions of the request elements
are displayed below the left pane.
After the request is posted, the output response is displayed in the right pane.
The following sections describe the commands to manage NX-API and descriptions of the elements of the
request and the output response.

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


5
NX-API
NX-API Management Commands

NX-API Management Commands


You can enable and manage NX-API with the CLI commands listed in the following table.

Table 1: NX-API Management Commands

NX-API Management Command Description


feature nxapi Enables NX-API.

no feature nxapi Disables NX-API.

nxapi {http|https} port port Specifies a port.

no nxapi {http|https} Disables HTTP/HTTPS.

show nxapi Displays port information.

nxapi certificate certpath key keypath Specifies the upload of the following:
• HTTPS certificate when certpath is specified.
• HTTPS key when keypath is specified.

nxapi certificate enable Enables a certificate.

NX-API Request Elements


NX-API request elements are sent to the device in XML format or JSON format. The HTTP header of the
request must identify the content type of the request.
You use the NX-API elements that are listed in the following table to specify a CLI command:

Table 2: NX-API Request Elements

NX-API Request Element Description


version Specifies the NX-API version.

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


6
NX-API
NX-API Request Elements

NX-API Request Element Description


type Specifies the type of command to be executed.
The following types of commands are supported:
• cli_show
CLI show commands that expect structured output. If the
command does not support XML output, an error message
is returned.
• cli_show_ascii
CLI show commands that expect ASCII output. This aligns
with existing scripts that parse ASCII output. Users are able
to use existing scripts with minimal changes.
• cli_conf
CLI configuration commands.

Note • Each command is only executable with the current


user's authority.
• The pipe operation is supported in the output when
the message type is ASCII. If the output is in XML
format, the pipe operation is not supported.
• A maximum of 10 consecutive show commands are
supported. If the number of show commands
exceeds 10, the 11th and subsequent commands are
ignored.
• No interactive commands are supported.

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


7
NX-API
NX-API Request Elements

NX-API Request Element Description


chunk Some show commands can return a large amount of output. For
the NX-API client to start processing the output before the entire
command completes, NX-API supports output chunking for show
commands.
Enable or disable chunk with the following settings:
0 Do not chunk output.

1 Chunk output.

Note Only show commands support chunking. When a series


of show commands are entered, only the first command
is chunked and returned.
The output message format is XML. (XML is the default.)
Special characters, such as < or >, are converted to form
a valid XML message (< is converted into &lt; > is
converted into &gt).
You can use XML SAX to parse the chunked output.
Note When chunking is enabled, the message format is limited
to XML. JSON output format is not supported when
chunking is enabled.
sid The session ID element is valid only when the response message
is chunked. To retrieve the next chunk of the message, you must
specify a sid to match the sid of the previous response message.

input Input can be one command or multiple commands. However,


commands that belong to different message types should not be
mixed. For example, show commands are cli_show message type
and are not supported in cli_conf mode.
Note Multiple commands are separated with " ; ". (The ; must
be surrounded with single blank characters.)
The following are examples of multiple commands:
cli_show show version ; show interface brief ; show
vlan

cli_conf interface Eth4/1 ; no shut ; switchport

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


8
NX-API
NX-API Response Elements

NX-API Request Element Description


output_format The available output message formats are the following:
xml Specifies output in XML format.

json Specifies output in JSON format.

Note The Cisco Nexus 5000 and 6000 Series CLI supports
XML output, which means that the JSON output is
converted from XML. The conversion is processed on the
switch.
To manage the computational overhead, the JSON output
is determined by the amount of output. If the output
exceeds 1 MB, the output is returned in XML format.
When the output is chunked, only XML output is
supported.
The content-type header in the HTTP/HTTPS headers
indicate the type of response format (XML or JSON).

NX-API Response Elements


The NX-API elements that respond to a CLI command are listed in the following table:

Table 3: NX-API Response Elements

NX-API Response Element Description


version NX-API version.

type Type of command to be executed.

sid Session ID of the response. This element is valid only when the response
message is chunked.

outputs Tag that encloses all command outputs.


When multiple commands are in cli_show or cli_show_ascii, each
command output is enclosed by a single output tag.
When the message type is cli_conf or bash, there is a single output tag for
all the commands because cli_conf and bash commands require context.

output Tag that encloses the output of a single command output.


For cli_conf and bash message types, this element contains the outputs of
all the commands.

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


9
NX-API
Command Types

NX-API Response Element Description


input Tag that encloses a single command that was specified in the request. This
element helps associate a request input element with the appropriate
response output element.

body Body of the command response.

code Error code returned from the command execution.


NX-API uses standard HTTP error codes as described by the Hypertext
Transfer Protocol (HTTP) Status Code Registry
(http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).

msg Error message associated with the returned error code.

Command Types
There are a number of command “types” available for sending show and configuration commands to a device
using the NX-API. The type you need to use depends on the actual command you want to send: cli_show:
You should use the “cli_show” type when you want to send a show command that supports structured XML
output. To know whether a command supports XML output or not, you can go to the CLI of the switch and
run the command with the "| xml" option on the end—you will be able to see whether that command returns
XML output or not. If you try and use the "cli_show" command type with a command that does not support
XML, you will receive a message stating “structured output unsupported” from the API:

<?xml version="1.0" encoding="UTF-8"?>


<ins_api>
<type>cli_show</type>
<version>0.1</version>
<sid>eoc</sid>
<outputs>
<output>
<input>show clock</input>
<msg>Structured output unsupported</msg>
<code>501</code>
</output>
</outputs>
</ins_api>
If that happens, you will need to use the command type— "cli_show_ascii".
• cli_show_ascii—This command type returns output in ASCII format with the entire output inside one
<body> element. Any command on the switch (including the ones that do not support structured XML
output) should work with this command type, although it will be more difficult to parse compared to
those commands that return XML.
• cli_conf— Use this command type when you want to send configuration commands (as opposed to
show commands) to the API.

Additional References
This section provides additional information related to implementing NX-API.

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


10
NX-API
Additional References

• NX-API DevNet Community


• NX-API Github (NX-OS Programmability scripts)

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


11
NX-API
Additional References

Cisco Nexus 5000 and 6000 Series NX-OS Programmability Guide


12

You might also like