VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

Understanding the
vSphere Automation
 API

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.
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 Supervisor
, 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
vRealize 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.

Content feedback and comments