VMware introduced a
new API service in vSphere 6.5 version which is known as vSphere Automation
API. This service allows us to introduce several new SDKs for JAVA, Perl, Ruby,
REST etc. Today we will see how to setup
the basic wizard to start using the API service in day to day life.
For more information
about what was introduced with the vSphere Automation APIs visit Here
Documentation :
The documentation
for this SDK version is pretty straight forward. We can browse to each level of
API and see the sections of what the operations it performs. We can get the
URL, JSON , XML representation for each and every operations in the document.
SDK tool kit:
You can download the
SDK kit from VMware {code}
Tools required:
We will use Postman
today so that we will be able to start working with the API quickly and build
your knowledge of how it works before using API in your own application.
Postman is a great application to design, build and test Rest APIs. Postman
have clients available for Windows, Mac and Linux platforms.
We shall download
Postman from link
First we need to gain access to the vSphere
Automation SDK for REST from VMware’s GitHub repository. 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:
- Click on the green “Clone or Download” button and then click “Download ZIP”
- Once downloaded, extract the zip file to the location of your choosing
At this point, you
will now have a local copy of the repository
Cloning can also be
done through the GitHub Desktop client as follows:
- Click on the green “Clone or Download” button and then click “Open in Desktop”
- Within the newly opened “Clone As” window, select the appropriate directory and name, then select “Clone”
So now we have the SDK ready in our local repository and let's get the Postman configured to be working. Open the Postman app and sign in to it
Welcome Page:
Initial Setup:
- vSphere-Automation-Rest-API-Resources.postman.json
- vSphere-Automation-Rest-API-Samples.postman.json
Choose the files which we have downloaded from GitHub
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.
Import the
Certificates if you are using Customer signed certificates
Disable SSL
verification if you do not use CA signed certs
Go to File >
Settings > SSL Certificate Verification ( set to OFF)
Once done, try connecting to the vCenter. 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.
Play around with the Environment:
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 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-1021’ 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.
Likewise you can go further and get the details of each object using the POST commands. You can also create a VMs using the "Create VM" function right over the list.
Make yourself comfortable with the basics and I see you soon with the next steps in next thread. :-)