REST Access to vSphere APIsLast Updated December 16, 2024
This
chapter shows how to run example programs by using the
vSphere Automation REST
API
and the Virtual Infrastructure JSON API
.The example code used here is in the form of a
bash
shell script that
invokes curl
commands and captures the results in environment variables
that can be used by subsequent curl
commands. The example code creates
a 'hello' folder and applies a 'hello' tag. The example is divided into sections for
clarity, but you can copy and paste the sections into a single plain text file named
example.sh
and execute it with the command bash
example.sh
in the directory where you saved the file.If you have access to a Unix or Linux development machine, you might need to use your
Linux distribution's package manager to install the
jq
utility, which
is used to parse JSON response bodies. If you have access to a Windows development
machine, you can run the bash example by first installing the Cygwin utility, which
provides a Unix-like shell, then installing the jq
package that is
available for Cygwin.Installing Cygwin for
Windows
To use this bash shell script example on
Windows, install Cygwin and the jq packages:
- Download and run the Cygwin setup executable.
- Answer the installation configuration questions.
- SelectUp to Datefrom theViewpull-down menu and click through to install the Cygwin base packages.
- Run the Cygwin setup executable again.
- SelectFullfrom theViewpull-down menu and search forjq.
- For thejqandlibjq1packages, change the value in theNewcolumn fromSkipto the latest release, then click through to install thejqdependencies.
Basic Authentication to the VIM
API
Starting with vSphere 8.0 Update 1, you
can use the
Virtual Infrastructure JSON API
as a substitute for
the SOAP-based vSphere Management API
. The Virtual
Infrastructure JSON API
is an HTTP-based wire protocol that maps
directly to the vSphere Management API
. The Virtual
Infrastructure JSON API
follows a resource-based REST architecture
with JavaScript Object Notation (JSON) requests and responses. You use the main CRUD
(Create, Retrieve, Update, Delete) functions over HTTP to manage object
representations.- To authenticate with theVirtual Infrastructure JSON API, you must first retrieve theSessionManagermanaged object ID by using theService Instance Get Contentoperation.
- Then, you use theSessionManager Loginservice to retrieve a session identifier for theVirtual Infrastructure JSON API.In the response headers, you receive thevmware-api-session-id:<mySessionIdentifier>key-value pair. Use it in the header of subsequent API requests for authentication.
Creating a Hello Folder with the
VIM API Through REST
The
ServiceContent
object contains a reference to the root folder of the managed object hierarchy. You
can retrieve that reference by using the ServiceInstance Get
Content
operation. Then you invoke the CreateFolder()
method on the rootFolder
object to create a subfolder named
Hello
Folder
.Basic Authentication to the
vSphere Automation API
vSphere Automation
API To obtain a session identifier, you call
the
Create Session
service with the base-64 encoded value of your
vCenter
Single Sign-On
user name and
password separated by a colon (username:password
) in the
authorization header.In the response, you receive the
vmware-api-session-id:<mySessionIdentifier>
key-value
pair. Use it in the header of subsequent API calls for authentication.Tagging the Hello World Folder
with the Automation API Through REST
To tag a folder, start by creating a tag
category, then create a tag in that category, and finally associate the tag with the
folder.
- Create a tag category.The response contains the details of the newly created tag category, including its UUID.
- Create a tag in that category. Use the tag category ID you created in the previous step.The response contains the details of the newly created tag, including its UUID.
- Associate the tag with theHello Worldfolder. You must have theHello Worldfolder ID and the tag ID you created in the previous step.
On success, the operation returns HTTP Code 204 - No Content.