Aside of vRO, Postman is a great tool to test single API calls. In many cases I use Postman to test the API call and transfer the body, used in Postman, into the API call structure in vRO.
For REST I am using the workflow “Add a REST host” to use this object (REST:RESTHost) within the workflows. I am not adding all the different REST calls to inventory, because it messes it up (because of too many) and changing the calls is more complex compared to build the calls on the fly inside the workflow. At this point we could discuss the reusability of code, but that is not part of this blog article.
Understand the API documentation
Before we’re able to understand the documentation, we need to download it. It is a PDF. Here is the link for the 6.4 version:
https://docs.vmware.com/en/VMware-NSX-Data-Center-for-vSphere/6.4/nsx_64_api.pdf
The documentation has a standardized schema which is very useful, because we use the same process or approach over and over. Let’s start with the endpoint which is the base URI for all API calls. Here is a screenshot from the document:
As we can see, the base URI is always https://<nsxmgr-fqdn>/api
Furthermore, the documentation shows us which parameters are required and which are optional. This is really helpful.
That is a great start. Before using the API we need to authenticate against the API. Otherwise NSX won’t accept any command or call we are sending.
Later I’ll use enabling syslog on the NSX controllers as an example, but first we need to look into the API documentation. That’s how it looks like:
It tells us everything we need to know and we will use that piece of documentation, to build our API call including the body.
Authentication
NSX uses basic authentication (not a token compared to the other VMware products). Therefor we need to build an authentication param. The RESTAuthenticationManager object is very helpful, because it has this functionality built-in. The downside of basic authentication is, that we need to add this part to each API call we do. In this case, it makes perfect sense if you would place that in an action and refer the action in the Javascript code. For a better centralized management, the needed data for the action (e.g. the session type) could be referenced using a configuration element. For ease of use and readability, I am not using an action.
Basic NSX API call
Now that we’ve already discussed the authentication for the NSX REST API, it’s time to build our first REST call. Let’s start with something simple. Let’s enable CDO mode for the NSX controllers.
As I’ve already mentioned, I am using the REST:RESThost object as an attribute and authentication was discussed in the previous section.
The REST call consists of three main parts:
- The URL - this is very simple, collected from the API documentation, no additional discussion
- Header including authentication
- Body - talking about NSX-v 6.4, this is XML
Let’s add the header information. Again our REST:RESThost object comes into play, because it offers adding header information.
restHost.setHeader("Accept", "application/xml");
restHost.setHeader("Content-Type", "application/xml");
Now that we’ve added all needed header information, it’s time to build the body. Referring to the documentation, we add the XML data needed to enable the CDO mode for the NSX controllers. Of course, for real automation, we need to change some data within the XML data structure. I am using E4X syntax doing this, for small XML data structures, or for large ones with a not defined size (e.g. firewall rulesets) those objects can be built on the fly too. I’ll cover that in a separate article. Enabling CDO mode is a great example, because it’s done directly via a query parameter and no body is needed.
As you observe, if no body is needed for the request, we add a null object instead.
If a body is needed, depending on the size, I create it either on top or one element previously to the REST call. Nevertheless, the content is always the same.
Finally, I would like to share a sample body as reference. As an example, I use the body to enable syslog on the NSX controllers, because this has to be done via the API anyways. I decided to not only share the body. Instead I show the whole REST API call, including all the discussed topics too.
Additional information: as you’ll see, I am using a controller array. The array was built before, collecting all the controller ID’s from the NSX manager, because syslog is enabled on a per controller base and, according to the documentation, the controller ID is part of the URL.
As an IP address I’ve used a fake IP address from a private IP range.
PLEASE NOTE: the request contains the XML, but at the end I’ve used the .toString() method to convert the XML object into a string. Otherwise the REST API won’t understand the body of the request.
Have fun creating your own cool automation via REST of NSX-v. If you have any questions or need additional information, you know where to find me.
Thanks for reading.
