6 issues with vSphere's RESTful API

This post is meant as a warning for users who are thinking to leverage vSphere’s RESTful API. More importantly, we hope that someone on vSphere’s team will read this and take action.

First, some brief history. vSphere's RESTful API, or Automation API as it is officially called, was introduced in v6.5. This initial version was lacking but in v6.7 it got better. Still, annoying issues persisted and going into v7.0 we were expecting to see some major improvements.

In Mist v4.3 we extended our support to vSphere v7.0. We were also planning to port our integration from the old SOAP API to the RESTful one. Unfortunately, the transition was impossible due to several issues.

In summary:

1. Calls for listings of resources return only a limited number of items and have no pagination.
2. You can’t use VM templates that reside in folders.
3. There is no way to resize disks.
4. UIDs are returned only for VMs but not for other resources e.g. clusters, hosts, datastores etc.
5. There is no information about hierarchical structures.
6. You need to juggle through requests to get the IP of a VM.

Keep on reading for more details.

1. Pagination

Automation API responses lack pagination and have a hard limit on the number of returned items. For example, "GET /rest/vcenter/vm" returns up to 4,000 VMs (reference). In v6.7-U3 the limit used to be 1,000.

What do you do if you have more than 4,000 VMs?

You first need to get all hosts with GET /rest/vcenter/host and then do a separate request for each one with GET /rest/vcenter/vm?filter.hosts={{host-id}}.

Keep in mind that GET /rest/vcenter/host has a hard limit of 2,500 hosts (reference). If you have more, you need an additional layer of nesting, e.g. get all datacenters, then loop for hosts and then loop for machines. Iterating like this, adds complexity and slows down code execution.

2. VM templates in folders

The Automation API supports only VM templates in Content Libraries (reference). It totally ignores templates in folders. No call returns them and there is no way to perform any action, e.g. move them to a Content Library.

This is a surprising omission, especially if you consider that VM templates are commonly used to deploy new machines. The only thing you can do is move your templates to a Content Library before using the Automation API.

3. Disk resize

There is no call to resize a disk. You can change the number of CPUs and the size of RAM, but not the disk. To add more disk space to a machine, your only option is to create a new disk and attach it. You are also unable to copy data between disks.

Bottom line, if you need disk resizing stick to the SOAP API.

4. UIDs and MoIDs

Starting in v7.0, the Automation API returns UIDs of VMs. For other types of resources you have to settle with Managed Object Identifiers (MoIDs). The problem is that MoIDs are not unique across vCenters.

This seems like a small fix, since the information is already there. We hope it will be available soon. Until then, be careful with IDs when you manage infrastructure on multiple vCenters.

5. Hierarchical structures

Several objects in vSphere have a hierarchical structure. For example, datacenter -> cluster, cluster -> host, host -> VM, folder -> VM etc.

Information about such structures is totally absent from API responses. To recreate it, you need to loop through all sorts of lists.

Let’s assume you want to find the folder in which a VM resides:

1. Get all folders with GET /rest/vcenter/folder. Notice that there is a limit of 1,000 returned items and the response includes only folder name, MoID and type (reference).
2. For each folder do GET /rest/vcenter/vm?filter.folders={folder-id}.
3. Then check if your VM is included in the response.

Such representations are useful very often and it’s hard to justify why they are not part of the API already.

6. VM IPs

If you want the get the IP of a machine you need to:

1. GET /rest/vcenter/vm/{vm-id} and get the NICs part. There you will find MAC addresses (reference).
2. GET /rest/appliance/networking/interfaces, for a list of all available interfaces. This is the only call that returns IP information (reference).
3. Search through the list of interfaces for the relevant MAC address and get the IP you need.

One would expect the IP to be available from the first call above (1) or at least offer a simpler way to cross reference items between calls.

Conclusion

In this post we went over the issues we had with vSphere’s Automation API. We also suggested some workarounds wherever possible.

Having to build and maintain integrations with more than 20 infrastructure platform APIs, we are accustomed to idiosyncrasies and annoying issues. Unfortunately, in the case of the Automation API the issues were too many to deal with.

Our hope is that future releases will solve these issues and the Automation API will become a first-class citizen in vSphere’s suite.