agsandrew - Fotolia


The vSphere REST API adds new dimensions to automation

The new vSphere REST API comes with a number of advanced capabilities that simplify automation and management. Here are a few ways to best use its capabilities.

VSphere 6.5 features the new REST-based API, which has garnered attention for its simple, developer-friendly design....

But in reality, will it make a difference in the life of the average administrator? The answer to that depends on a few factors.

VMware was one of the first non-Microsoft companies to get on board with PowerShell and PowerCLI, both of which have their pros and cons. In a world of self-service portals and web applications, scripting has limitations on what it can achieve and where you can use it. It's more difficult to use scripting in conjunction with orchestration, as it's complicated to react dynamically to entry selections.

For example, the vRealize Automation self-service portal uses JavaScript to interact and update user options depending on previously-selected options. PowerShell scripting can't do this in an easily implemented manner. Put bluntly, PowerShell isn't perfect, and it can be difficult for some administrator to work with a laundry list of commands. But PowerShell can use REST APIs with some built-in commands.

Implementing a consumable REST-based API, however, adds new dimensions to automation capabilities. The REST API decouples data from the programming language by decoupling the language dependencies and frameworks. An administrator can use JavaScript, Python, Perl, PowerShell, C/C++ or even the Unix/Linux CLI tool -- using the curl command -- to extract data from the VMware system using a vSphere REST API.

How to use the vSphere REST API

The REST API vCenter login page shows different API calls that only admins can use to get and set data. If this information were available to end users, it could cause a litany of issues. The REST API has a built-in authentication mechanism that uses authentication calls to create a secure session and prevent unauthorized users from gaining access.

The REST API has a built-in authentication mechanism that uses authentication calls to create a secure session and prevent unauthorized users from gaining access.

To see the scope of the REST-based API's functionality, click the "Browse vSphere REST APIs" link in the login page. You can implement these functions programmatically, but, as an example, we can use the VMware API webpage explorer to try out some of the calls.

Before going any further, it's important to understand some key components that comprise the REST framework. To do so, use four key HTTP actions.

The Get API extracts information about VMs, vCenter properties and anything else the API exposes. The Set keyword sends or updates information. For example, you can use Set to create a VM. The Put method updates an entire group of items; using Put will overwrite anything that is already there.

The Post API is slightly different than Put because it only adds items. Essentially, you can use Put to build up items individually. As the name implies, Delete tells the API that it calls to delete a process and deletes the item passed.

While this may look a little strange, the keywords and paths basically represent the information the administrator wants. Figure A shows an example of these HTML methods.

VSphere REST API HTML methods.
Figure A. REST API HTTP actions.

To see how this works, click the first line, /vcenter/datacenter/ to display several items. At the bottom of the page, you'll notice a button called Try it out. Click that button to run the query and report back. My local vCenter is shown in Figure B.

Response to a REST query.
Figure B. Example response to a REST query.

The response might look a little odd because the website is reporting back in key:pair value. This is essentially a description ID and value. The name of my vCenter is "LocalDC" and the data center is "datacenter-2."

To repeat the same query using cURL, copy and paste the curl command to get the same data. To suppress warnings about insecure certificates, add the -k switch to the command.

Use curl to retrieve data.
Figure C. Use curl to retrieve data.

You can safely experiment using the Get method, but practice extreme caution using other methods, as you could potentially damage the infrastructure.

It's useful to learn how to use the new vSphere REST API, especially if your automation is web-driven or uses several disparate systems, such as external load balancers that support REST calls. As you learn new tools and languages, continue to leverage the REST API. One benefit of the REST functionality in vSphere 6.5 is that it's OS- and language-independent; however, moving everything to REST is still a work in progress.

Next Steps

Organizations modernize with RESTful APIs

What's the difference between PowerCLI and vRealize Orchestrator?

Save time and effort with IT automation

Dig Deeper on VMware new releases and updates