If you have a small home lab or use virtualization on your desktop PC or laptop you must hear about VMware Workstation – a hosted hypervisor that runs on the x64 version of Windows or Linux. It is a really good product for all engineers and enthusiasts that do not have or don’t need dedicated server-class hardware for they work. You can even run ESXi hypervisor as VMware Workstation virtual machine. What you could not do is manage the configuration and virtual machines in a programmable way. You had to do everything manually via GUI interface. Not anymore! The gap is filled with the REST API in VMWare Workstation 15 release that hit the market late September.

The REST API features are limited to 20 operations including the most essential ones and match the features in VMware Fusion 10. This includes VM management, VM power management as well as host and guest virtual networking. Let’s take a quick look at how it works.

You need to enable REST API first

The REST API is disabled by default for security reasons. Before you run it you need to configure the credentials for REST API access. The credentials are stored locally and are independent of operating system credentials. To define login and password you need to run the

vmrest.exe -C

(or

vmrest -C

on Linux). Then you need to configure the service as HTTP or HTTPS for both local and remote access. If you want to use the HTTP just issue the

vmrest.exe

. By default, it uses port 8697 but you can provide other using the

-p

parameter. The unencrypted service will only bind to the loopback address and you cannot change it.

If you want to access REST API remotely you need to activate the HTTPS listener. You need to create the encryption key and certificate first. It can be in either DER or PEM format. You can find the instruction on how to generate the certificate and the key, as well as how to act as CA, in my post ‘
How to act as your own local CA and sign certificate request from ASA‘. Then you need to provide them as command parameters

vmrest.exe -i 192.168.1.2 -c host.crt -k host.key

The obvious disadvantage is that REST API service will be available as long as the command line is open. I think it should be available as Windows Service.

REST API covers almost all I need, except one thing

If you use any web browser to connect to previously specified service IP address and port you can browse the REST API interactive documentation. At the top right webpage corner, you can find the Authorization link. Using it, you can provide previously configured credentials and use the Try it out! button available for every method and test how the REST API is working without using the external software like the Postman. The documentation also contains a description of all structures used in.

If you use third party software or developing you own application or script the REST API requires header Basic Auth authorization for each call. 

I won’t jump into describing the operations available via REST API. Let’s say you can perform most of the usual tasks on the VM and basic operations on Host networking configuration. You can change the VM state by powering it on or off, suspending, resuming, pausing and unpausing but you cannot reset it using one call. Remember this executes the host operation, not the Guest OS if VMware Tools are installed. You can read many parameters of running VM and its NICs and change some. Because in my home lab I have dedicated configuration for staging the new VM I found handy that I can change the NIC MAC address because MAC address determines assignment to staging VLAN and what IP address DHCP server will provide. 

The limitations

The major limitation I see now is that you cannot create an empty VM or import one from OVA file. All you can do is create a copy of existing VM. If you need to create new VM and then manually install the OS you still need to have access to the VM console. You also don’t have access to most of the VM parameters via REST API – network, memory, and CPU are the only ones you can read or edit. The similar situation is when you import the OVA, and you need to go through the wizard. In both cases, I can think of workarounds such as hardcoding some of the VM configuration parameters or providing them in JSON. It will at least solve the problem for some engineers in simpler deployment scenarios. The person using the REST API and VMware Workstation itself will know what path to ISO or OVA file provide by example.

Hopefully VMware will still continue to develop new features and on Windows will convert it to system service. They filled the technology gap but still have to improve the feature.