Author : Michael A. Haines, Prasenjit Sarkar
In the third part (and subsequent posts) of this blog series on the REST API, we are going to focus on a few of the common tools that enable you to interact with the REST API. This is by no means complete or comprehensive (and it not intended to be), but serves as an introduction about a few of the most commonly used UI and Command Line tools that I have seen and that you can also use to interact with the REST API.
- REST Client – cURL
- REST Client – Firefox RESTClient 2.0.3 Extension
- REST Client – Java RESTClient WizTools.org from VMware
- NSX for vSphere Networking and Security API Programming Guide
- vSphere Managed Object Browser
- XML Validator
- xmllint(1) command-line utility
- Base 64 Encoding
I am going to start with cURL (as this is one my favourite tools) and what I mostly use. I just like the simplicity of this command line tool, though there are many options that can be used to, so you have the best of both worlds, nice hey!
cURL Client – Installing
- cURL is installed by default on most current Operating Systems and is normally located in /usr/bin/curl
- If cURL is not installed then obtain the curl executable source code (curl 7.40.0 was released on the 8th of January 2015) or curl binary. Note that the curl source code and binary releases are not always at the same release level. This depends on what options curl is compiled with at runtime.
- Now, if you download the source code to build your own version of curl with your own options, you will download the current file which is curl-7.40.0.tar.gz. This file is a gzip tar file so do the following to extract the contents and follow this procedure (on performed on Mac OS X).
- Decompress and untar the curl file you downloaded
- cd into the curl directory that was automatically created
- In a typical unix installation after you have unpacked the source code will be to configure (choose what options you require) followed by a make, then a make install to install the curl binary.
- When the configure process has completed successfully you will see the following:
- Now run make (of course you will need a compiler installed). I use gcc.
- Run make
- Now run make install
- The curl binary will now be installed as in the following example if all the above steps have completed successfully.
- Now we have the latest curl binary installed we can test it! What is the most basic test you can perform? Well, something like this.
- This will return (if successful) the following. I can not be much more simpler than that hey! You are looking for 200 OK which is as we discussed in the introduction to the REST API – Part II REST Request Methods and Responses, the return code of 200 is the return code the client hopes to see! It indicates that the REST API successfully carried out whatever action the client requested, and that no more specific code in the 2xx series is appropriate.
Now that we have looked at the very basics of getting the latest version of curl(1) installed, let us now focus on interacting with the REST API using curl(1) to communicate with VMware’s NSX for vSphere Networking and Security Platform.
So, where do we begin? First, we need to know what the required configuration options used by the curl(1) client are for us to communicate successfully with the NSX for vSphere platform. The following table shows the curl(1) options that will be used in the following examples.
Now that we know what the the basic options we are going to use are, we can now perform some basic testing. I consider the following REST API example below to be akin to a ping(8) test. I mean this is probably one if not the simplest REST API requests you can send to the NSX for vSphere Manager. I also suggest that whenever you are working with the REST API and NSX for vSphere platform, that this is one command you always start with, as this proves basic communication.
Also remember that All REST APIs require authentication using Basic HTTP authentication. Each request must be authenticated individually. User names must also be either the local NSX for vSphere users or vCenter Server users added to the NSX for vSphere Manager with the appropriate role and scope assignments.
Enumerating the supported versions of the REST API with NSX for vSphere
- URL : /api/versions
- GET Method
In the example above you are going to enter the password of the user “admin” and the IP Address of the NSX for vSphere Manager. Once you have correctly provided these two parameters you will see the following output :
Anyway, I digress, what I wanted to say is that based on our example above it would be so useful to get the REST API Request data returned in the JSON format. However, there is an issue currently with the NSX for vSphere platform, and that is that JSON is NOT currently SUPPORTED. What will happen is if you try and return the REST API Request in the JSON data format, you will get a message informing you that “No JSON object could be decoded“. It is not all bad news, as in the fact that there are numerous objects in the NSX for vSphere platform that can be returned in the JSON data format. Please do read this point carefully, the JSON data format is NOT officially SUPPORTED in the current release of the NSX for vSphere Platform (Version: 6.1.2 Build 2318232).
So, this being the case how can I return the REST API Response in a more human readable way? Well, there are a few options available to you. When using the command-line I use a utility which is part of Mac OS X called xmllint(1) and if you want to use a UI option, then something like the Firefox RESTClient 2.0.3 Extension will work admirably for you. In the next Blog posts we will cover both xmllint(1) and the Firefox RESTClient.
The cURL source code and binaries are available from the following location: