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

and run 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:

C:\Program Files (x86)\VMware\VMware Workstation>vmrest --config VMware Workstation REST API Copyright (C) 2018 VMware Inc. All Rights Reserved vmrest 1.1.0 build-8888902 Username:alex New password: Retype new password: Processing... Credential updated successfully 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 C : \ Program Files ( x86 ) \ VMware \ VMware Workstation > vmrest -- config VMware Workstation REST API Copyright ( C ) 2018 VMware Inc . All Rights Reserved vmrest 1.1.0 build - 8888902 Username : alex New password : Retype new password : Processing . . . Credential updated successfully

In Fusion, the following procedure looks like as follows:

MacBook-Pro-alex:Public alex$ ./vmrest -C VMware Fusion REST API Copyright (C) 2015-2017 VMware Inc. All Rights Reserved vmrest 1.0.0 build 6754183 Username:alex New password: Retype new password: Processing... Credential updated successfully 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 MacBook - Pro - alex : Public alex $ . / vmrest - C VMware Fusion REST API Copyright ( C ) 2015 - 2017 VMware Inc . All Rights Reserved vmrest 1.0.0 build 6754183 Username : alex New password : Retype new password : Processing . . . Credential updated successfully

Now, you can start using REST API:

In Fusion, you need to execute the ./vmrest command

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.

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.

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).

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).

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.

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.

methods. They are 100% safe because they only read data. PUT methods are highlighted in yellow. They involve adjusting settings.

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).

– 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:

VSAN from StarWind eliminates any need for physical shared storage just by mirroring internal flash and storage resources between hypervisor servers. Furthermore, the solution can be run on the off-the-shelf hardware. Such design allows VSAN from StarWind to not only achieve high performance and efficient hardware utilization but also reduce operational and capital expenses. Learn more about ➡ VSAN from StarWind

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:

Views All Time Views All Time 2 Views Today Views Today 19

Appreciate how useful this article was to you?

5 out of 5, based on 1 review 5 out of 5, based on 1 review

Loading... Loading...