You can use the vSphere Automation REST services to automate many aspects of your vSphere environment such as configuration, authentication, certificate management, tagging, managing the life cycle of clusters, content libraries, Kubernetes cluster management, and many more.

How Does the vSphere Automation API Work

The vSphere Automation API follows a resource-based REST architecture with JavaScript Object Notation (JSON) requests and responses. REST, an acronym for Representational State Transfer, is a software architectural style in which programs use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects between a client and a server. The client sends an HTTP request and receives an HTTP response from the server. Request and response bodies are encoded using JSON, and must conform to the JSON schema associated with each operation.

The vSphere Automation API uses the main CRUD (Create, Retrieve, Update, Delete) functions over HTTP to manage representations of the objects that the API defines. In the vSphere Automation API, these objects are represented by a collection of JSON schemas.

You use:
  • HTTP GET to retrieve a representation of an object
  • HTTP POST to create an object
  • HTTP PATCH or PUT to modify an object
  • HTTP DELETE to delete an object
In addition, the HTTP POST operation is used for some custom actions outside of the CRUD framework such as registering or relocating virtual machines.

The HTTP verbs are also called methods. Each API operation is identified by a method and a URL. Operations can also contain a body that is composed of one or more data structures. The operation body contains parameters that are structured as key-value pairs. For more information, see vSphere Automation API Requests.

The vSphere Automation API in Context

To take full advantage of the vSphere Automation API, you must understand the broader context in which it functions.

Figure 1. vCenter Server Automation Architecture
You can use code or tools to automate vCenter Server. All automation passes through the vSphere Web Services API or the vSphere Automation API.
vSphere Automation API: the REST API for vSphere Management

The underlying platform of the vSphere Automation API is vSphere, which consists of vCenter Server and ESXi. The vSphere Automation API is available to all licensed vSphere users.

Starting with vSphere 6.0, VMware introduced the vSphere Automation API to supplement the SOAP-based vSphere Web Services API. Since then, VMware engineers have been designing new vSphere features with a RESTful approach and these new services have been integrated into the vSphere Automation API. As a result, you can now use the vSphere Automation API to manage and automate many aspects of your vSphere environment such as vCenter Server configuration, authentication, tagging, content libraries, managing the life cycle of clusters, managing internal and external certificates, vSphere Trust Authority, vSphere IaaS control plane, and so on.

However, you cannot manage all aspects of your vSphere environment with the vSphere Automation API as it does not cover all vSphere features. To expose the full set of vSphere functionalities you must use both the vSphere Automation API and the vSphere Web Services API. For both APIs, VMware has compiled SDKs that help programmers automate tasks.

vSphere Web Services API: the SOAP API for vSphere Management

The vSphere Web Services API, which is based on the SOAP protocol, provides basic vSphere functionalities such as host management, virtual machine provisioning, monitoring, vSAN and many more. It uses port 443 and the /sdk and /sdk/vim25 base paths. The vSphere Web Services API can be consumed through:

  • the vSphere Management SDK for Java

  • the Python SDK for managing vSphere (pyVmomi)

  • the Virtual Infrastructure JSON API

    Starting in vSphere version 8.0.1, you can communicate with the vSphere Web Services API by using HTTP and JSON. For more information, see the vSphere Web Services SDK Programming Guide.

  • customer generated bindings from the WSDL files included in the vSphere Management SDK

vSphere Automation API Ports

The vSphere Automation API uses the standard HTTPS network port 443. A subset of the vSphere Automation API related to appliance configuration and life cycle is available also on port 5480. You can use the services on port 5480 immediately after installing vCenter Server and during life cycle and configuration operations when the services on port 443 are unavailable.

vSphere Automation API Base Paths

All existing and non-deprecated HTTP operations of the vSphere Automation API are available on port 443 and the /api base path. The APIs released up to vSphere version 7.0.2 are also available on the deprecated /rest base path. The /api base path will remain the only active base path when the /rest base path is removed in a future vSphere release.

vSphere Automation API Security

The vSphere Automation REST APIs are designed with security best practices in mind. The HTTP link between the client application and the vSphere Automation API is established through the Transport Layer Security (TLS) cryptographic protocol. User identity security is guaranteed by token-based authentication and by the OAuth 2.0 workflows for federated authentication.

SDKs for the vSphere Automation API

VMware supports open-source SDKs that empower developers to consume the vSphere Automation API through a programming language. The vSphere Automation SDK for Java and the vSphere Automation SDK for Python contain tools, libraries, documentation, and sample code for vSphere automation. Both SDKs are based on the JSON-RPC protocol. You can download or contribute to the vSphere Automation SDKs on GitHub.

vSphere Automation Tools

Automation tools such as PowerCLI, Data Center CLI (DCLI), and VMware Aria Automation Orchestrator provide another option for consuming the vSphere APIs. For example, you can use PowerCLI and the vSphere Automation SDK for PowerShell to communicate directly with the vSphere Automation API by using PowerShell scripts. For more information, see the PowerCLI User's Guide.

User Interface Tools

User interface tools such as the vSphere Client and the vCenter Server Management Interface consume the vSphere Automation API and the vSphere Web Services API in the back end.

Which REST Clients to Use with the vSphere Automation API

Client Applications for REST

You can use any REST client to communicate with the vSphere Automation API.

Some popular applications are:

API Explorer in the vSphere Client

Use the API Explorer, a built-in tool in the vSphere Client, to explore and try out vSphere APIs.

Why Use the vSphere Automation API Through REST

You can choose whether to access the vSphere Automation API directly through REST or through the various SDKs and automation tools binded to the API.

Possible use cases for using the vSphere Automation API through REST:

  • There is no SDK available for your programming language. For example, you use PHP, JavaScript, Swift, Rust, and so on.

  • Your integration footprint is small and you can't justify the overhead of installing and maintaining the vSphere Automation SDKs for Java or Python. For example, if you are designing a client application that fetches a few parameters from your vSphere environment, you might decide that installing and maintaining the Java or Python SDKs is unnecessary.