How does REST API work in VMware Fusion and VMware Workstation?

VMware introduced REST API in VMware Fusion 10, the desktop virtualization platform for MacOS, back in the last fall. This interface enables to orchestrate not only the virtualization platform itself but also virtual machines running on top of it. Exact the same REST API appeared in the recently released VMware Workstation 2018 Tech Preview. However, there’s a small thing about the API for Workstation: it works only on Windows hosts so far.

What is REST API for?

REST API provides control over various virtual machine functions (i.e., inventory, power, cloning, networking, IP, MAC, etc.). It allows running automated tests on the virtual machines that typically involve cloning, configuring, and further virtual machine removal. Unfortunately, these features are available only for Windows.

Getting under the hood

So, that we know what REST API is for, let’s study how it works.

First, let’s set login and password to configure the access to the REST API:

• To set REST API credentials on the virtual machine with Workstation, go to C:\Program Files (x86)\VMware\VMware Workstation and run vmrest.exe –config there
• In VMware Fusion, go to /Applications/VMware Fusion.app/Contents/Public and run the ./vmrest -C command

In Workstation, you will be asked to set the username and password:

In Fusion, the following procedure looks like as follows:

Now, you can start using REST API:

• In Fusion, you need to execute the ./vmrest command
• In Workstation, just run vmrest.exe

Web server starts on your workstation shortly after starting REST API. There, you can access the API using both browser and some third-party REST clients or systems you intend to integrate with Workstation or Fusion. For Workstation, use the following address to access the web server through the default port:

http:\\127.0.0.1:8697

For Fusion, use just the same link. Sure, you can just type localhost instead of 127.0.0.1:

http:\\localhost:8697

The further procedure looks the same for both platforms. So, we won’t be specific about the platform anymore.

The first thing you see on the web server is REST API Explorer running in the Swagger interface. There, you can learn about available tools for working with host and virtual machines:

Notably, you do not need Curl, PowerShell, Postman, or any other instruments to test the key API features.

Talking about tools, everything looks pretty straightforward:

• Host Networks Management enables to list all virtual networks on the host, add, modify, and delete port forwarding.
• Maintenance allows configuring the daemon. Here, you can turn it off if you need going into the maintenance mode.
• VM Management provides means of virtual machines orchestration (e.g., list VMs, configure, clone, and delete them).
• VM Network Adapters Management servers for managing VM network adapters (e.g., get network adapters list, acquire VM IPs list, update or delete VM network adapters).
• VM Power Management enables to keep an eye on VM power state.
• VM Shared Folders Management allows mounting, unmounting, and changing the configuration of the host shared folders.

Once you access the web interface, you need to authorize. For that purpose, just click Authorize in the upper right corner and type credentials you have specified at the beginning:

To check all available operations, press the Show/Hide button:

Pay attention to color coding. It helps you figure out what exactly you do while testing the API:

• Blue color stands for GET methods. They are 100% safe because they only read data.
• PUT methods are highlighted in yellow. They involve adjusting settings.
• Green stands for POST – new entities creation (e.g., network adapters), or doing some operations (e.g., cloning VM).
• DELETE methods are highlighted in red. As it comes from the name, they are used to delete entities.

If you need to learn more about an operation, just click on its line.

First, let’s look at GET /vms, the operation for VM management:

Once you expand the option, you can get under the hood of the JSON array for parameters acquisition.

Scroll down and find the TRY IT OUT! button. Hit it to get the list of virtual machines IDs and their paths in the host system. You’ll get the response in the Response Body area:

Here, we got Response Code 200. Sure, there are other Response Codes, and you should better take a closer look at them:

Now, let’s study the PUT method. It enables to adjust virtual machine settings. For instance, let’s get under PUT /vms/{id} hood. This operation allows changing the number of VM processors and dedicated memory volume:

If you click Example Value on the right, this value will be transferred to the parameters field. The only thing you should do is changing the numbers. Once you are done with the parameters, press the TRY IT OUT! button. The new VM configuration will be displayed in the Response Body field.

You also can create a virtual machine network adapter. Use POST method for that purpose:

And, you can delete it with the DELETE method. Note that Response Code now is 204, not 200 as we saw before:

NOTE: VM is deleted without any confirmation in this case. So, be careful!

Next, you can access REST API Workstation or Fusion with any REST client (e.g., PowerShell or Postman). Still, the easiest way is using Curl for that purpose. Should you need more on how to do this, check out William Lam’s article.

Conclusion

Today, we took a closer look at what REST API is and how it works in the latest VMware Fusion and VMware Workstation Tech Preview. Also, we studied the basics of how to use it and when it may come in handy.

Related materials:

•  Consuming a RestFul API with PowerShell
• Why should you install the latest VMware vCenter 6.5 Update 1d /1e?