REST - Using the vSphere Automation SDK

vSphere 6.5 introduced a big update to its newest API service, which is known as the vSphere Automation API. This API is a big step forward in the process of simplifying and modernizing our APIs. This service also allows us to introduce several new SDKs for the following programming languages: Java, Python, .NET, Perl, Ruby, and REST. This blog will take a look at the REST SDK and how to easily get started using it.

For more information about what was introduced with the vSphere Automation APIs, check out the associated What’s New blog post.

Accessing the SDK

First things first, we need to gain access to the vSphere Automation SDK for REST from VMware’s GitHub repository: https://github.com/vmware/vsphere-automation-sdk-rest Make sure to read through the README, noting that we’ll be able to view and use these resources, as well as contribute back to the following items:

• vSphere Automation SDK for REST API Reference Documentation
• Postman Samples
• Javascript Samples (we’ll cover these here, as part two)

The easiest method is now to either download or clone the repository.

Downloading can be done as follows:

1. Click on the green “Clone or Download” button and then click “Download ZIP”
2. Once downloaded, extract the zip file to the location of your choosing
3. At this point, you will now have a local copy of the repository

Cloning can be done as follows by CLI:

1. Click on the green “Clone or Download” button and then copy the clone URL
2. Within Terminal, change to the appropriate directory, and enter the following command: git clone [Copied URL]
3. Once the tasks complete, you will now have a local copy of the repository

Cloning can also be done through the GitHub Desktop client as follows:

1. Click on the green “Clone or Download” button and then click “Open in Desktop”
2. Within the newly opened “Clone As” window, select the appropriate directory and name, then select “Clone”

Documentation

The documentation for this SDK has improved so much it deserves its own section. The documentation is just clean and straight forward. Looking at it from a high level, you can browse each API and see the sections of what the underlying operations cover. Each of the operations list the method, URL, and a brief description of what it’s used for. To receive some more in-depth information, click on the operation’s method. Here you’ll see all the information needed in order to perform the request including the request parameters, response codes, JSON and XML response representations, followed by a table of what those response types mean, and it also covers the error codes.

Install Postman

One of the most convenient ways to get started using this SDK is with the Postman application. If you’ve never heard of Postman, it is a simple and free REST API client. It can be installed on Windows, OSX, and Linux (although this is currently a beta install). While there is a Chrome app, we have found the best experience is with the full client application.

Postman can be downloaded at the following link: https://www.getpostman.com/apps

Initial Setup

At this point we have the SDK downloaded and the recommended client installed, so let’s get Postman setup with everything needed to work with the SDK.

First, start by importing the collections which were downloaded as part of the SDK. This can be done by clicking the “Import” button. On the new screen, with “Import File” selected, click the orange “Choose Files” button, browse to the location where you unzipped the SDK and then navigate to: client\samples\postman. Select the two JSON files in the directory titled:

• vSphere-Automation-Rest-API-Resources.postman.json
• vSphere-Automation-Rest-API-Samples.postman.json

We’ll now notice two new collections which are named quite similarly to the files imported. The vSphere Automation REST Resources collection is a number of requests, grouped in folders by their object level, that can be performed against a vSphere environment. The vSphere Automation REST Samples is a couple groups of requests which can be combined to perform a normal task. Some of the examples include ESXi host connection and disconnection, VM creation, and VM power actions.

Last part of setup comes down to configuring some environmental variables. As you begin browsing through the requests, you’ll start noticing some double curly brackets that may look like this: {{vc}} This is what’s known as an environmental variable within Postman, and vc will be used to refer to the vCenter Server. There’s only a couple environmental variables which need to be set in order to begin: vc, user, password. Those are fairly self-explanatory, so let’s set them up in Postman.

To begin creating environmental variables, head towards the gear icon in the top right hand side and click on it. This is where environments are managed. Add a new environment by clicking on the orange “Add” button. Give the environment a name, then enter in those three items mentioned above and valid values for your environment. Click the orange “Add” button again to complete the creation, and click on the “X” to the right of “Manage Environments” to close the window.

Getting Authenticated

As with all vSphere environments, the first step is to authenticate. Expand the vSphere Automation REST Resources collection, expand the Authentication folder, and select Login.

We can gather a bit of information about the request at this point. We’ll be doing a Post method to the vCenter’s URL of /rest/com/cmware/cis/session with a basic authentication type and sourcing the username and password from our environmental variables. Before making the request, make sure to select the environment that was just created by selecting it via dropdown box next to the gear icon on the top right hand side.

NOTE: If you have any issues, you may need to turn off SSL certificate verification in the Settings (File > Settings > General tab > SSL certificate verification, turn off, restart Postman)

Environment Discovery

We’re now authenticated to the vCenter’s API endpoint, so we can start exploring some other areas within the vSphere Automation REST Resources section. Let’s do some environmental discovery while we’re still exploring the SDK. To get a list of the hosts available by this vCenter’s API endpoint, expand the Hosts folder and select List. Here we can see the request uses a Get method to the vCenter’s URL of /rest/vcenter/host. Clicking “Send” will give us a list of the hosts available as well as some basic information such as the host ID, name, connection state, and power state.

To get a list of the datastores available by this vCenter’s API endpoint, expand the Datastores folder and select List. This request is very similar to the last request, except it points to the vCenter’s URL of /rest/vcenter/datastore. Clicking “Send” will give us a list of the datastores available as well as their datastore ID, name, type, free space and capacity.

To get a list of the VMs available by this vCenter’s API endpoint, expand the VM folder and select List. At this point, hopefully you can figure out what the request is going to look like and a rough guess at what information is going to be pulled back.

We’ve got the basics down now, how about getting into some additional detail on a VM. In the VM folder, select the Details. In the URL, we’re just appending the VM’s ID to the end of the prior call. The example includes ‘vm-22’ which can be modified to a VM ID as identified in the prior request. Clicking on “Send” retrieves a ton of information back about the configuration settings for that VM including CPU information, NICs, boot configuration, and so forth.

VM Creation

Last example, creating a VM. We’ve just seen all of the configuration settings for a VM, however we don’t need to have all of those to create a VM with this SDK. The API endpoint has the capability of setting those options automatically per best practices and VMware’s guidance. These decisions are all based on the guest OS type.

We’ll start by selecting the “Create with defaults” option. Notice the familiar URL, however we’re performing a Post method on it this time. Switching over to the “Body” section, we can see some items have already been filled in for us like Guest OS type, datastore, folder, and resource pool. These are the basics in order to perform this request.

Once those options have been filled in with valid values for your environment, click the blue “Send” button to create the VM.

You should see a response that resembles a VM ID. Run the VM Details request again, only this time substituting the new VM’s ID in the request URL. Scrolling through the response’s body, take note of many of the areas which were populated automatically. Things like memory, disk size, SCSI controller, even the name were all populated automatically.

If you’ve done this through the API before, this is a tremendous improvement! If there are additional things you’d like to specify, that’s possible as well. If you want to populate the settings for all of those items, that too is possible. It is all about the user’s choice.

Wrapping Up

We just scratched the surface on what’s possible with this SDK and Postman. There’s many more areas to check out and explore. There’s also the samples collection to take a look at too.