NSX REST API Primer #1: Connecting with cURL

By | November 7, 2014

Welcome to part one of a new series detailing the use of the NSX REST API. My goal is to highlight several administrative tasks of your VMware NSX environment that have been exposed via API. I will assume that the reader has an entry level understanding of layer 2 & 3 networking and where we go a bit deeper I will explain what is going on. I will not assume the reader has used a REST API before and the instructions will be clearly broken down.

Simply put a REST API is a programmatic way of Creating, Reading, Updating, and Deleting objects and attributes by transferring data via http or https. The API behind NSX is extensive and very powerful. Hopefully reading these primers will assist you in scripting and automating  your NSX environment to give you better control and ease of scale.

There are several ways to send or POST our commands to NSX, we could write a script in Ruby, use Powershell, use the Chrome REST API plugin, or use a command line tool like cURL. For ease of explanation I will be using cURL in the posts.

Before we start turning commands into a global enterprise SDN, we need to learn how to connect to NSX with cURL. If you run OSX or most distros of Linux open terminal and you should have cURL. Folks using Windows need to install the package. I’ve found the easiest way is to install Git for Windows from git-scm.com. Choose the option to integrate with cmd and you get access to cURL and several other powerful Linuxy tools.

Ok, so now I’ll assume you can execute cURL from your command line of choice. To query NSX we will use the following syntax:

curl -k -u user:password https://[NSX Manger IP or Hostname]/api/[api version]/[path1]/.../[pathN]

Lets break this down. First we have the command switches for cURL, -k and -u. The -k switch tells cURL not to check the validity of the certificate. If you are using self signed certs, this is a must. The second switch, -u, allows us to specify a username and password. The default username and password for NSX Manager is admin:default. I will be using this in all examples from this point forward.

The next input that we give cURL is the URL we are sending to the NSX API. It is important to note that ALL API calls to NSX are directed to the NSX Manager, regardless of what you are trying to manage. The URL tells the API exactly what we want to know and it is formatted in a specific way.

The URL will always start with https://. If you send an unencrypted request you will get no response.

Next is the IP Address or Hostname of the NSX Manager, followed by /api then with API version of the specific request. This varies so pay attention to what the specific endpoint calls for.

After the API version number comes the rest of the path. This will tell the API what we want to do and specify our target.

Now that we understand the basic syntax, lets look a simple request to get information about the default user “admin”.

Type the following command using your NSX Manager IP or Hostname, and your password for the “admin” account:

curl -k -u admin:default https://nsx-man-001.vbyron.lab/api/2.0/services/usermgmt/user/admin

The path is fairly easy to understand. We are asking the NSX Manager to call the User Management Service and return information about the user named “admin”. If all goes right, you will be returned a long string of XML with the information. Since are are using cURL the response is an unformatted blob of XML and not super readable out of the gate. To fix this lets pipe our output to tidy.

curl -k -u admin:default https://nsx-man-001.vbyron.lab/api/2.0/services/usermgmt/user/admin | tidy -xml -indent -quiet

nsx1-2

Ok, that looks much better. Now let’s see what the User Manager service is telling us about ‘admin’.

The first tag tells us the XML encoding format, which will always be utf-8.

Next we have information about the object that has been returned:

Object ID: userinfo-3

Object Type Name: User Info

VSM (vShield Manger) UUID: 564D5CC7-C550-EF43-37F8-AA520C8C5FA9

Revision: 0

Following the object descriptor tags we gave the data about admin that we asked for listed after the type tag:

Name: admin

User ID: admin

Is Local?: False

is Enabled?: True

is a Group?: False

is Cli? (granted CLI access): True

Has Global Object access?: True

Access Control Entry (ACE) Role: super-user

Even in this simple example it is clear that one query can return quite a bit of information. When you query things like full NSX Edge configs there is even more.

Pulling this data manually can give you useful information, however it is even better when you use the API for automation.

Stay tuned and in future primers I’ll explain how to create and delete objects, write data as well as read it and then proceed into advanced topics like leveraging the API for automation.

Until then stay well, keep in touch, and do good work.