vSphere Automation API Requests

To retrieve or manage resources, clients make HTTP requests to a vSphere Automation API server.

An API request through HTTP must include a method (or verb), a URL, and headers. Depending on the type of operation, the request might or might not include a body.

HTTP Method

The methods of the vSphere Automation API follow the logic of the CRUD (Create, Retrieve, Update, Delete) functions used to interact with database applications.

Table 1. vSphere Automation API Methods

HTTP Method/Verb	Operation Type	Operation Summary
POST	Create	Creates a resource. Also used for some custom actions such as registering or relocating virtual machines.
GET	Retrieve	Retrieves the representation of an existing resource in its current state.
PUT	Update	Updates or replaces an entire resource.
PATCH	Update	Updates or replaces a part of a resource.
DELETE	Delete	Deletes a resource.

URL

You can reach each vSphere Automation API operation through a specific URL.

The URL is typically composed of:

• the vCenter Server IP address or FQDN.

• the /api base path

• the package name

• the service (also called interface) name

• the resource identifier (if applicable)

https://<vcenter_server_ip_address_or_fqdn>/api/<package_name>/<service_name>/<resource_identifier>

To determine what you want to do with the resource, you associate an HTTP verb (POST, GET, PUT, PATCH, or DELETE) to the URL.

For example, to retrieve information about a virtual machine, you contact the VM service of the vcenter package with the GET method. You pass the virtual machine identifier as a path parameter.

GET https://<vcenter_server_ip_address_or_fqdn>/api/vcenter/vm/<vm_identifier>

HTTP Headers

The HTTP headers transfer metadata associated with the API requests and responses. They are an integral part of HTTP requests and responses as they convey information about authorization, request and response content type, response caching, and so on.

You must typically set the following HTTP headers in your requests.

Authorization

All requests to create a vSphere Automation API session must include an Authorization header in the form prescribed by your identity provider. For vCenter Single Sign-On basic authentication, you must use the base-64 encoded value of your user name and password separated by a colon ( username:password). For more information, see Authentication Mechanisms.

vmware-api-session-id

This is a custom header that you use to authenticate your subsequent calls after you obtain a session identifier. Paste the session identifier as the header value.

Content-Type

This header is used to indicate the data format of the request body.

Use application/x-www-form-urlencoded for requests to the Authentication Token service.

Use application/json for all other requests.

Request Body

The HTTP body must be in the JSON format.

Some vSphere Automation API requests contain a body and some do not. For example, retrieve (GET) operations do not contain a body in the request.

To explore the request and response schemas, visit the vSphere Automation API Reference.