REST Access to vSphere APIs

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:
  1. Download and run the Cygwin setup executable.
  2. Answer the installation configuration questions.
  3. Select
    Up to Date
    from the
    View
    pull-down menu and click through to install the Cygwin base packages.
  4. Run the Cygwin setup executable again.
  5. Select
    Full
    from the
    View
    pull-down menu and search for
    jq
    .
  6. For the
    jq
    and
    libjq1
    packages, change the value in the
    New
    column from
    Skip
    to the latest release, then click through to install the
    jq
    dependencies.

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.
  1. To authenticate with the
    Virtual Infrastructure JSON API
    , you must first retrieve the
    SessionManager
    managed object ID by using the
    Service Instance Get Content
    operation.
    SESSION_MANAGER_MOID=$(curl -k https://$VC/sdk/vim25/8.0.1.0/ServiceInstance/ServiceInstance/content \ | jq .sessionManager.value \ | xargs -t)
  2. Then, you use the
    SessionManager Login
    service to retrieve a session identifier for the
    Virtual Infrastructure JSON API
    .
    VC='vc1.example.com' UNAME='administrator@vsphere.local' PWORD='TooSecret2C!' curl -v -k "https://$VC/sdk/vim25/8.0.1.0/SessionManager/$SESSION_MANAGER_MOID/Login" \ -H 'Content-Type: application/json' \ -d '{"userName": <myUsername>, "password": <myPassword>}' BODY='{"userName": "'"$UNAME"'", "password": "'"$PWORD"'"}' VIM_SESSION_ID=$(curl -k -i "https://$VC/sdk/vim25/8.0.1.0/SessionManager/$SESSION_MANAGER_MOID/Login" \ -H 'Content-Type: application/json' \ -d "$BODY" \ | tr -d '\r' \ | awk '/vmware-api-session-id/ {print $2}' )
    In the response headers, you receive the
    vmware-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
.
echo 'Using REST to create Hello Folder.' BODY='{"name": "Hello Folder"}' AUTH_H="vmware-api-session-id: $SESSION_ID" HELLO_FOLDER_MOID=$(curl -kv \ "https://$VC/sdk/vim25/8.0.1.0/Folder/$ROOT_FOLDER_MOID/CreateFolder" \ -H "$AUTH_H" -H "Content-Type: application/json" \ -d "$BODY" \ | jq .object.value \ | xargs -t) echo HELLO_FOLDER_MOID=${HELLO_FOLDER_MOID}

Basic Authentication to the
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.
auth=$(printf '%s:%s' "$UNAME" "$PWORD" | base64) VAPI_SESSION_ID=$(curl -k -i -X POST -H "Authorization: Basic $auth" "https://$VC/api/session" \ | tr -d '\r' \ | awk '/vmware-api-session-id/ {print $2}' )
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.
  1. Create a tag category.
    echo 'Using REST to create tag category.' BODY='{"name": "hello_category", "description": "A tag category for custom folders", "cardinality": "SINGLE", "associable_types": ["Folder"]}' CAT_ID=$(curl -k \ -X POST \ -H "vmware-api-session-id: $VAPI_SESSION_ID" \ -H "Content-Type: application/json" \ -d "$BODY" \ "https://$VC/api/cis/tagging/category" \ | xargs -t)
    The response contains the details of the newly created tag category, including its UUID.
  2. Create a tag in that category. Use the tag category ID you created in the previous step.
    echo 'Using REST to create tag.' BODY='{"name": "hello_tag", "description": "example of a tag from Automation API", "category_id": "'${CAT_ID}'"}' TAG_ID=$(curl -k \ -X POST \ -H "vmware-api-session-id: $VAPI_SESSION_ID" \ -H "Content-Type: application/json" \ -d "$BODY" \ "https://$VC/api/cis/tagging/tag" \ | xargs -t)
    The response contains the details of the newly created tag, including its UUID.
  3. Associate the tag with the
    Hello World
    folder. You must have the
    Hello World
    folder ID and the tag ID you created in the previous step.
echo 'Using REST to tag Hello Folder.' BODY='{ "object_id": {"id": "'${HELLO_FOLDER_MOID}'", "type": "Folder"} }' curl -k \ -X POST \ -H "vmware-api-session-id: $VAPI_SESSION_ID" \ -H "Content-Type: application/json" \ -d "$BODY" \ "https://$VC/api/cis/tagging/tag-association/${TAG_ID}?action=attach"
On success, the operation returns HTTP Code 204 - No Content.