The feature I am most interested in is the REST API. After listening to Craig Dalrymplepresent a session at the last Scottish VMUG called Making Your 1st Restful API call to VMware I wanted to try using an API. I had not tried it in my home lab or production at work as I didn’t want to screw anything up, so using Workstation is ideal.

Starting the REST API

The REST API needs to be started from the command line. The file you need to run is located in C:\Program Files (x86)\VMware\VMware Workstation. You can then vmrest.exe --help to see some basic help:

You can see that there is a web based Swagger interface for browsing the API on http:\\127.0.0.1:8697:

Authentication

If you now try to do anything through the API it will not work as we are not authenticated. We need to configure some credentials. This is done using vmrest --config but remember if the API is running you will need to stop it by pressing CTRL+C:

You simply enter a username and password for authentication to the API. Start the REST API again using vmrest.exe. Now in the web interface click the Authorize link in the top right, enter the username and password and then click the Authorize button:

There does not seem to be any visual indication that you are logged in, the only way to check is to do something.

Swagger Interface

The Swagger interface is a great way to try the API. You don’t need to use things like Curl, PowerShell, Postman, etc. you can simply use the web interface to perform API operations. You can see that there are four main sections available with various operations available under them:

There are quite a few operations available in the API. Lets try out a few.

Simple GET Operation

A quick check to see if things are working right is to use the Swagger interface and try a GET operation. GET means reading something, no changes are made – safe!

Browse to VM Management...Show/Hide..GET /vms then click TRY IT OUT! The Response Body shows the two VM’s I have in Workstation:

So in the above screenshot you can see from the interface some useful information. We can see what the response should look like, the HTTP response codes (200 means we were successful), the Curl command, and what we actually want to see, the Response body:

Now we have a list of the VM’s and their IDs we can try something else. Let’s get some VM setting information for a particular VM. To do this use GET /vms/{id}. In the web interface expand VM Management...Show/Hide..GET /vms/{id}. Under the parameter section we need to use one of the ids from above, in this case I will use "id": "RG98SS5QSA90GAP42Q7M4IVAT1VOH2EV".

In the parameters section it is looking for parameter of id. Copy and paste the id of the VM into the field:

One this id is entered click TRY IT OUT!. The Response Body section gives us the details of the VM:

The VM has a single CPU with 64MB of RAM.

Simple PUT Operation

A PUT operation updates something. In this case we want to add a CPU and some memory to a VM. This is under VM Management...Show/Hide..PUT /vms/{id}. We again need to define some details in the Parameters section. The first is the id of the VM like we did above.

Next we need to add some definition of what the VM needs to be changed too. This is in the parameters text box. There is an example shown just to the right:

Again click the TRY IT NOW! button and we get the response:

The VM now has 2 CPUs and double the amount of RAM. We can check using the API again:

DELETE Operation

Finally I want to delete the VM as I am done with it. This is found under VM Management...Show/Hide..DELETE /vms/{id}. There is a warning with DELETE operations. Unlike the GUI there is no confirmation or check you actually want to delete, it just does it. So be aware!

Again we need to define the id of the VM we want to delete then click TRY IT OUT!. This time we get a Response Body and Response Code of:

Not the usual response we have seen above. Usually we get a Response Code of 200, but this time it’s 204. That is 204? Scroll up in the web interface and you see:

So 204 is the VM was deleted. We can confirm using GET /vms:

The VM with the id of RG98SS5QSA90GAP42Q7M4IVAT1VOH2EV is gone.

Wrap Up

When I started with this blog post I had never used an API before, but within an hour I was using the Swagger interface to interface with VMware Workstation. 30 minutes later I was using Postman to do the same. I think using the ‘safety’ of Workstation to get used to the VMware API is a great way of learning how to using the API.

I plan to investigate further as I use Workstation as my lab, so being able to automate operations using the API could help me a great deal. I expect further development of the API as the Tech Preview progresses.