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='[email protected]'
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.