About NX-API
NX-API is an enhancement to the Cisco MDS 9000 Series CLI system. NX-API improves the accessibility of the CLIs that are run on the Cisco MDS 9000 devices by making them available outside the switch by using HTTP or HTTPS. CLIs are encoded into the HTTP or HTTPS POST body. NX-API supports certain show commands, and configuration commands that are noninteractive.
Note |
A noninteractive command is a command that does not prompt the user to enter an input from the keyboard to proceed further. |
NX-API supports XML, JSON, and JSON-RPC formats for commands and their outputs.
You can use any REST-based tool to interact with a Cisco MDS device. You can also use your own web-based mobile tool that supports sending and receiving HTTP or HTTPS requests and responses to interact with the device.
NX-API Workflow
The NX-API backend uses the NGINX HTTP server. The NGINX server looks out for requests on the HTTP port. Note that HTTPS support is not enabled by default. It has to be enabled by NX-API CLIs.
NX-API Performance
NX-API performance depends on the following factors:
-
HTTP and HTTPS—NX-API performance on an HTTP server is better compared to that on an HTTPS server. This is because an HTTPS server has an overhead of encrypting and decrypting data to provide more security.
-
Device (memory and process limitation)—NX-API performance is better in devices with more memory.
-
Command output size—NX-API performance is better when the command outputs are smaller.
-
Parsed and unparsed output of show commands—NX-API performance is better with unparsed outputs.
Message Format
-
NX-API output presents information in a user-friendly format.
-
NX-API does not map directly to the Cisco NX-OS NETCONF implementation.
-
NX-API output of supported commands can be viewed in XML, JSON, and JSON-RPC formats.
Security
By default, NX-API uses HTTP basic authentication. All command requests must contain the username and password of the device in the HTTP header. NX-API can also leverage HTTPS to secure and encrypt data. An HTTPS connection provides more security over an HTTP connection.
In Cisco NX-OS Release 8.1(x), and 8.2(x), when NX-API is enabled over HTTPS, a 2K SHA-1 self-signed certificate is created. This certificate is valid for two years. When an expired certificate is used, the browser displays a warning about security vulnerabilities. To avoid such vulnerabilities, we recommend the use of a CA-signed certificate. In Cisco NX-OS Release 8.3(x), the self-signed certificate expires after 24 hours. We recommend that you use a CA-signed certificate for this release too.
NX-API is integrated into the authentication system of the supported Cisco MDS switches. Users must have appropriate accounts (network-admin, network-operator, and so on) to access a switch through NX-API.
NX-API performs authentication through a programmable authentication module (PAM) on a switch. Use cookies to reduce the number of PAM authentications, which in turn reduces the load on the PAM.
NX-API provides a session-based cookie, nxapi_auth when users first authenticate successfully. An nxapi_auth cookie expires in 600 seconds (10 minutes). This value is fixed and cannot be configured. The session cookie is used to avoid reauthentication during communication. If the session-based cookie is not included with subsequent requests, another session-based cookie is required; this is obtained through a full authentication process. Avoiding unnecessary use of the authentication process helps to reduce the workload of the device.
Supported Switches
NX-API is supported on the following Cisco MDS 9000 Series Switches:
-
Cisco MDS 9700 Series Switches
-
Cisco MDS 9250i Multiservice Fabric Switch
-
Cisco MDS 9396T Multilayer Fabric Switch
-
Cisco MDS 9396S Multilayer Fabric Switch
-
Cisco MDS 9148T Multilayer Fabric Switch
-
Cisco MDS 9148S Multilayer Fabric Switch
Limitations
-
The XML output of the commands listed below will not be supported if the interface type (Fibre Channel or Ethernet) is not explicitly specified. The XML output of these commands is supported only if a Fibre Channel or Ethernet interface is specified in the command. For example, show interface ifid bbcredit .
-
show interface
-
show interface bbcredit
-
show interface brief
-
show interface capabilities
-
show interface counters
-
show interface debounce
-
show interface description
-
show interface detail-counters
-
-
The XML outputs of FCIP interface related commands are not supported.
Note |
For more information on platforms supported in Cisco MDS NX-OS Release 8.x, see the Cisco MDS 9000 Series Compatibility Matrix, Release 8.x. |