Cisco NX-API on Nexus 5500

This week I will dive more into a network programmability topic. I will show you a practical use case for the Cisco NX-API. It provides an interface to communicate with a Nexus device using HTTP/HTTPs using JSON or XML. Because of the reliable request-response nature of the HTTP protocol, it is usually more preferable than scraping Telnet/SSH outputs.

The use case or “how to build an interface description cleaner”

Last week during lunchtime, I talked to a colleague about interface descriptions and how reliable they are (he ran into a little issue because of wrong interface descriptions during troubleshooting…). I think you know the answer: they are normally not very reliable, especially in environments where many people make logical and physical changes. The documentation mostly occurred in spreadsheets and Visio documents, but in many times not directly in the configuration. I start to think about a programmatic way to update these information based on CDP.

I read about the Cisco NX-API within the context of the Nexus 9k in NX-OS mode some time ago on the blog of Jason Edelman. The environment that my colleague talked about was a Nexus 7k and 5k environment and since some months, the Cisco NX-API is also supported with the Nexus 7000, 6000 and 5000 platform using NX-OS Version 7.2.

Okay, we have the technology and the capabilities to write a short “interface description cleaner”. Before we dive into the python “magic”, lets have a look at the Cisco NX-API in more detail.

The Cisco NX-API

As already mentioned in the introduction, the Cisco NX-API provides an interface to communicate with a Nexus device using HTTP/HTTPs and JSON or XML. I prefer JSON because it is quite easy to parse it without any external library, therefore I will continue to use it within this example. The Cisco NX-API is supported on a broad range within the Cisco Nexus Switch platform, including but not limited to the Nexus 5500, 6000 and 7000 starting with NX-OS 7.2.

The Cisco NX-API is nothing else than a HTTP/HTTPs endpoint, where you can drop commands in a HTTP/HTTPs post request and get a response back, which contains structured or unstructured data in the JSON or XML data format. This interface has the benefit of HTTP/HTTPs in terms of simplicity, security (HTTPs) and usability within a python script.

Lets have a look at the example network and the python script.

The example network

Within the example network, we will use some Nexus 5500 (5596T and 5596UP in detail). First, we need to update the software to Versions 7.2. In earlier releases, the NX-API is not supported on these platforms. The sample network will look like the following picture.

I tested it with the NX-OS version 7.2.(1)N3 on the Nexus 5500. The Cisco NX-API requires some configuration in NX-OS as we will discuss in the next section.

Activate the Cisco NX-API on Nexus and the Sandbox

To activate the Cisco NX-API, you just need to activate the feature within the configuration mode. It is recommended to use non-default ports for the HTTP and HTTPS protocol when configuring the Cisco NX-API. We will change the HTTP port to 8080 in the following example. The following commands are required:

(config)# feature nxapi
(config)# nxapi http port 8080

After this configuration, you can start using the Cisco NX-API. To get in touch with the format and the request and response structure, you can enable a browser based Sandbox directly on the switch using the following command:

(config)# nxapi sandbox

After this, you can access the switch using the web-browser. You will see a page, which looks similar to the following screenshot.

For security reasons, we will also enable the Cisco NX-API for HTTPS using the following command. We will also use a non-default port as recommended.

(config)# nxapi https port 8181

During my lab, I had a little issue that take some time to discover. As mentioned earlier, it is recommended to use non-default ports for the communication with the Cisco NX-API. If you will use the default ports anyway, it worked in my case for HTTP but not for HTTPs.

To verify the configuration of the Cisco NX-API, use the command show nxapi. It should look similar to the following screenshot.

The “interface description cleaner”

The interface description cleaner will discover the neighbor on an interface using CDP and changes the interface description using the following format:

interface <interface name/type>
 description *** <remote interface(short version)>, <hostname> (<management IP of the remote switch>)

The following screenshot shows the before and after state using the script on my example network.

Because of the complexity of the script, I will only explain how to use it in this post. I will come back to some of the implementation details in later posts.

In short, the python script does the following:

  • Utilize the Cisco NX-API to execute the show cdp neighbors detail command on the device(s). The Cisco NX-API will respond with structured data in JSON by default, which makes the parsing easier within the script.
  • Process the CDP neighbor output and create a simple neighbor table per host
  • Create a change script that configures the descriptions on the given interfaces based on the CDP information
  • Push the configuration script to the switch devices using the NX-API

The entire python script is structured in three sections: The first part contains the import statements, a list with the Cisco NX-OS switch IP’s, username, password and the HTTPs port used to communicate with the NX-API. The second part contains some helper functions to interact with the switches using the requests library, which is used to perform the HTTP/HTTPs calls. The third part is the script itself, which will use the two previous parts to call the NX-API and update the descriptions.

You can find the entire script on my python examples repository on GitHub in the file named “” within the “cisco-nx-api-example” folder.

I have not implemented a user interface in the example script, therefore you need to customize the following variables to test it in you own environment:

hosts = [

dev_username = "username"
dev_password = "password"


The script will only update the interface descriptions on ports, which has a CDP neighbor. All other interface descriptions are not changed.


This week I started with a “real network programmability” topic. Within this post, you see that you can interact with Cisco Nexus devices in a programmatic way using HTTP/HTTPs. It is similar to the interaction with a REST API, which I described within an earlier post on the blog, called REST API: A practical introduction.

That’s it for this week. I upload the example script from this post to my python example repository. Within the next posts, I will continue in the next months with a more detailed description, how to interact with REST APIs and the Cisco NX-API using the requests library. Now it’s up to you: What do you think about this solution? Do you have other use cases that might be interesting for the use of the Cisco NX-API? Run into trouble while testing the script? Please drop me a comment below, if you have some comment to this post.

Thanks for reading.