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

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

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.

Select

Up to Date

from the

View

pull-down menu and click through to install the Cygwin base packages.

Run the Cygwin setup executable again.

Select

Full

from the

View

pull-down menu and search for

For the

and

libjq1

packages, change the value in the

New

column from

Skip

to the latest release, then click through to install the

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.

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)

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.

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.

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.

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.

Getting Started with vSphere APIs and SDKs

Content feedback and comments

VMware vSphere SDKs and Tools 8.0

REST Access to vSphere APIs

Installing Cygwin for Windows

Basic Authentication to the VIM API

Creating a Hello Folder with the VIM API Through REST

Basic Authentication to the vSphere Automation API

Tagging the Hello World Folder with the Automation API Through REST

Basic Authentication to the
vSphere Automation
API