This post is part of my VMware VCIX-NV Study Guide and goes into the possibilities and some specifics of the NSX API.

Documentation

• NSX Administration Guide
• NSX Command Line Interface Reference
• NSX API Guide

Index

• Deploy and successfully authenticate an REST API client
• Construct and execute an API call using correct syntax and formatting
• Analyze, modify, and successfully retrieve configuration data using an existing API call

NSX API
The NSX Platform management is an open door. Through the NSX API you can deploy and configure all the different components. The API is used by third party vendors to deliver services inside NSX, inside automation tools (vRealize Automation) and for operational scripts.

To cover the VCIX-NV blueprint on the API, you need to know how to execute basic API calls to get information and create basic objects. Don’t expect that you need to be on the level of a developer (unless you’re developing an application on top of NSX of course 😉 ). Especially if your area of expertise is networking and you’re new to the application world, you need to play around with this. Create a few basic things; a logical switch, edge gateway, hook a VM to a logical switch, create a firewall rule, etc.

The API itself is located on the NSX Manager and goes through REST (REpresentational State Transfer) with a XML format as the configuration body. In non-developer speak: it uses different URLs for different operations (simplified for example: /getuser, /create/edge) and you can use HTTP operations such as GET (to retrieve information), POST (to push information, create objects), PUT (modify objects) and DELETE (to delete objects). The content of the call is structured in XML, details of which are specified in the NSX API Guide. So for example, creating a logical switch would result in a POST to https://nsxmanager/api/2.0/services/securitygroup/bulk/globalroot-0 with the XML content from the guide.

REST API calls are usually done from a bit of code, but there are handy browser plugins that allow you to do calls from inside your browser. Here are my favorites:

• Chrome: Postman
• Firefox: RESTClient

All API calls have to be authenticated using credentials to login to the NSX Manager. The credentials are encrypted using base64 and inserted into the HTTP header.

Let’s dig in.

Deploy and successfully authenticate an REST API client

We start by downloading and installing the REST Client. In the upcoming examples I’ll be using the Postman plugin in Chrome. The basic functionality of the different plugins are the same though, so the screenshots should look familiar on whichever you pick. Download and install a plugin of your choice before proceeding.

After installing a REST plugin and before you start making API calls, make sure the SSL certificate of the NSX Manager is trusted by your computer. If the NSX Manager has a self-signed certificate, you need to install that certificate in the trusted certificate store. If you do not do this and the SSL certificate is marked as untrusted (you get a popup upon visiting the NSX Manager SSL webpage), the REST Client will present you with a very non-descriptive error message (something like “Server returned 0”).

Now that you’ve got a REST Client and optionally installed a SSL self-signed certificate, we’ll start by doing a simple API call to get the CPU usage of the NSX Manager appliance.

Fire up the REST client. First thing you do is set up the authentication:

• Activate the “Basic Auth” tab.
• Fill out the “Username” and “Password” fields with the NSX Manager credentials.
• Click the “Refresh Headers” button to insert the “Authentication” HTTP header.

After inserting the authentication header, you can move on to the actual API call. Lets get that CPU information!

• Enter the API URL for the call you want to do. In this case that will be https://10.192.123.80/api/1.0/appliance-management/system/cpuinfo. Check the NSX API Guide for the specific URL for all the API calls you can execute.
• Make sure the HTTP method select box is set to “GET” (which is the default).
• Click the “Send” button to send the HTTP request.

The output is formatted in JSON which can be parsed by any programming or scripting language, or the naked eye. As you can see the NSX Manager had a CPU load of 21% at the time of the call.

Construct and execute an API call using correct syntax and formatting

The good news is that if you executed the API call in the previous bit, you know how to do this – congratulations! But lets go a bit further.

So getting information is pretty easy, all you need is a GET request to an URL. Creating objects is a bit more complex and you need to do a tiny bit more to pull that off. When pushing information to the API, an extra HTTP header needs to be set: “Content-Type” with value “application/xml”. Next to the extra header, the content (payload) needs to be formatted in the way NSX wants it. It is formatted as XML and the contents are specified in the NSX API Guide.

Lets do another example and add a NSX Security Tag. Here’s the formatted XML:

<securityTag>
  <objectTypeName>SecurityTag</objectTypeName>
  <type>
    <typeName>SecurityTag</typeName>
  </type>
  <name>My_Security_Tag_API</name>
  <description>I just created this tag through the API!</description>
  <extendedAttributes/>
</securityTag>

The properties of a Security Tag are pretty simplistic: a name and a description, that’s it. The other tags around it are the formatted command to create a security tag (that NSX API Guide is pretty important when you’re doing this). Let’s execute it:

After creating objects through the API, the returned result will mostly always be the identifier of the object. You’ll notice that this is not the name, it is usually the name of the type of object (in this case ‘securitytag’) and number. Especially when modifying objects and creating objects that refer to other objects (for example a new logical switch on a transport zone), these object identifiers are important.

Back to the security tag. The API call output returned an object identifier, which means the tag was created. When you double check in vCenter, you’ll see that the security tag actually has been created:

So now you’re able to get information from the NSX Manager and create objects. Lets move on to some more advanced stuff.

Analyze, modify, and successfully retrieve configuration data using an existing API call

To get a little deeper in the NSX API, we’re going to be adding several other NSX components through the API. We’re going to be adding a NSX controller, edge gateway and a logical switch.

If you’re adding objects that have relations to other vCenter objects, you need to get the vCenter identifiers for those objects. I’m talking a bit abstract because these objects have a very wide range. It can be a datacenter, datastore, network portgroup or IP Pool. These are all objects that have identifiers that we can use in API calls.

To retrieve object identifiers of existing vCenter objects, you can browse to https://yourvcenter/mob. Login with admin credentials, click the “content” link next to ServiceContent and look for the “rootFolder” row on the next page. Click the link in that row. Finally, click the link next to “childEntity” and you’ll have most of the identifiers displayed on the next page.

Adding a NSX controller
Adding a controller is pretty straightforward, but you need quite a lot of info before you can execute the API call. The call itself looks like this:

<controllerSpec>
<name>my-new-controller-api1</name>
<description>Created through the API</description>
<ipPoolId>ipaddresspool-1</ipPoolId>
<resourcePoolId>domain-c7</resourcePoolId>
<hostId>host-10</hostId>
<datastoreId>datastore-15</datastoreId>
<networkId>network-12</networkId>
<deployType>small</deployType>
<password>aPassword</password>
</controllerSpec>

URL: https://nsxmanager/api/2.0/vdc/controller

You should look up the exact format in the NSX API Guide, but you may notice a few references. When creating a NSX controller, either through the web interface or the API, you need the following information related to other configuration: IP Pool for it to get an IP address from, resource pool or cluster to be hosted in, ESXi node to be hosted on, datastore to place its VM files and a network port for management. You’ll need to browse the vCenter MOB to get the requred identifiers.

Adding a Edge Gateway
Now for something a bit higher on the difficulty scale. Adding a Edge Gateway requires a lot of input. Next to the usual stuff like datacenter, resource pool and datastore, we also have to ability to add interfaces. You can add up to 10 interfaces on an Edge, but I’ll limit this one to three: a management, uplink and internal interface.

<edge>
<datacenterMoid>datacenter-2</datacenterMoid>
<type>gatewayServices</type>
<appliances>
<appliance>
<resourcePoolId>resgroup-8</resourcePoolId>
<datastoreId>datastore-15</datastoreId>
</appliance>
</appliances>
<mgmtInterface>
<connectedToId>dvportgroup-59</connectedToId>
<addressGroups>
<addressGroup>
<primaryAddress>10.192.123.84</primaryAddress>
<subnetMask>255.255.252.0</subnetMask>
</addressGroup>
</addressGroups>
</mgmtInterface>
<interfaces>
<interface>
<type>uplink</type>
<mtu>1500</mtu>
<isConnected>true</isConnected>
<addressGroups>
<addressGroup>
<primaryAddress>10.192.192.10</primaryAddress>
<subnetMask>255.255.255.252</subnetMask>
</addressGroup>
</addressGroups>
<connectedToId>dvportgroup-32</connectedToId>
</interface>
<interface>
<type>internal</type>
<mtu>1500</mtu>
<isConnected>true</isConnected>
<addressGroups>
<addressGroup>
<primaryAddress>192.168.0.1</primaryAddress>
<subnetMask>255.255.255.0</subnetMask>
</addressGroup>
</addressGroups>
<connectedToId>dvportgroup-43</connectedToId>
</interface>
</interfaces>
</edge>

URL: https://nsxmanager/api/4.0/edges

When you look closely to this call, I trust that it looks logical, if you’ve come this far. 😉

Adding a Logical Switch
Creating logical switches is one of the easiest API calls. The reason why I’m using this as an example is because you need a scopeID to make this call. The scopeID is defined as a transport zone. As a transport zone is a native NSX component, you can retrieve, create and modify them as well. Quick note: transport zones are called Network Scopes in the API Guide. To keep it simple, I suppose. 😉

So this example will show a flow of getting information from the API and using that information again to do another call.

First we retrieve the existing transport zones by executing a simple GET to the URL: https://nsxmanager/api/2.0/vdn/scopes

Output is as follows:

There’s only one transport zone in this testlab, so the output is easy to read. If you’ve got multiple transport zones, there will be simply more <vdnScope> entities defined. We need to get the <objectId> value for the next call, make a note.

Next we create the logical switch by doing this call:

<virtualWireCreateSpec>
<name>t1-web-servers</name>
<description>Logical switch for T1 web servers</description>
<tenantId>Tenant 1</tenantId>
</virtualWireCreateSpec>

URL: https://nsxmanager/api/2.0/vdn/scopes/vdnscope-1/virtualwires (replace the vdnscope-1 with the transport zone object id)

If all goes well, the output of this call will be very slim. It’ll be just the logical switch object identifier, formatted as virtualwire-#. Here’s the example in Postman:

Just in case you don’t trust the API output yet, check inside vCenter whether it actually has been created:

If you’ve come this far, you’ve created some stuff through the API, got some information and got a general feel of working with the API. The VCIX-NV blueprint simply says that you should be able to work with the API. It does not differentiate between configuring your entire environment with the API or simply making a call to get some information.

My advice is to play with it a bit more, pull some more information from it, create some more things, modify those things. Do this until you’ve got making the calls down and are able to quickly analyse the output. Don’t forget to go through the NSX API Guide. You have this guide available during the exam, you should know it enough to find topics easily.

Have fun!

Share the wealth!