Hydra 1303

All News Items

Commanding with RESTful APIs

from the Hydra High Council Feb 4th 2020

When first learning to configure a Cisco router, the CLI was a bit intimidating. No graphics. All text. After learning how to use the question mark to get help with syntax, things got easier, but the desire to have a GUI interface was still on my Christmas list. Cisco eventually developed a generic one that could be used for routers, but by that time, the CLI had become so familiar that trying to figure out how to accomplish the same tasks, using a graphical screen of nested menus, took way more time than just entering the commands directly, and was not worth the hassle.

A case for text based commands

Although the learning curve was steeper, there was a big benefit to only using text commands. Scripting. I'm not a programmer, but I found that I could easily save some simple if/then commands within SecureCRT. These allowed me to automatically log in, place configurations on lab and production gear, script APCs to power devices in my rack on or off, and even configure entire lab environments for testing.

With VMware products, the GUI is the primary way to deploy and configure anything. However, other ways are available. Here, we're going to look at one alternative: the use of REST APIs. REST stands for Representational State Transfer. The idea is that by using the same HTTP commands our browsers use to GET, PUT, POST, or DELETE webpages, we can GET the status of a remote device (its state, represented in a message).

With a RESTful API, those GET commands can also issue remote procedure calls that go beyond simply reporting status. They can be used to configure a device. Or deploy a VM. Or for that matter, an entire data center. Essentially, anything you can do with the graphical vSphere client, you can do with REST API calls.

A different kind of texting

If you're unfamiliar with APIs (Application Program Interfaces), it's the code that allows two different applications to talk to each other, without both sides having to refactor or alter their application to allow the communication. Since the REST commands used by browsers essentially make up the language of the Internet, it makes sense that when it comes to connecting to cloud services, like AWS or GCP, sending commands to a REST interface is a natural, simple solution. Virtually any time you hear about connecting to a company's API (like Facebook), they are referring to a REST API.

REST is a client-server protocol. When connecting to vmware.com, for example, we have a client (the web browser) and a server (web server). By clicking a link, the GET command is issued in the background.


NSX has its own REST API. As an example, let's say we wanted to retrieve details about our NSX controller. The command itself is easy enough to understand. There's the action: GET, followed by a URL to locate the resource: nsx-mgr.hydra1303.lab (the server) and /api/2.0/vdn/controller (the specific resource on that server).

GET https://nsx-mgr.hydra1303.lab/api/2.0/vdn/controller

The response would look something like this:

From the output, we can see that the NSX controller is RUNNING, its IP is, and the version it's running is 6.4. The output is truncated here, but you get the idea.

In another post, we'll look at how you can use your browser to enter REST commands like this, as well as how to add your login credentials. Once you've gotten familiar with manually entering REST commands through a web browser, the next step is automate them through scripting.