When we hear REST API, we know it is relatively easy to consume these from a PowerShell script. So power up your labs and follow along on my first steps in my vSphere Audtomation SDK and PowerShell adventure.

Intro

The REST API were officially announced during VMworld EMEA 2016 in Barcelona.

Recently Kyle Ruddy published two blog posts on the VMware {code} blog that showed how to get started with both SDK.

Some Basics

As I already demonstrated in my Ravello module, it is quite easy to consume REST API with PowerShell. With the Invoke-WebRequest cmdlet calling REST API becomes a breeze.

A few basics one needs to be aware of.

The key function in the code is the Invoke-RestCall function. This function does the preparation of the parameters, the actual Invoke-WebRequest call and the handling of any errors resulting from the call. I’m also investigating of the use of Invoke-RestMethod would bring any advantages.

Separate methods will be wrapped in separate functions. For now I tried to use function names that resemble their PowerCLI counterparts. You’ll find Connect-rViServer, Get-rVMHost…

Authentication in my code, as well as in the SDK Samples, is done as Basic Authentication. Creating the Authorization string can be done with PowerShell and some .Net methods.

As most REST API libraries, the vSphere Automation API also use a “Session” string for all calls after the authentication call. When using the Invoke-WebRequest cmdlet, there is no need to create a header with a session cookie. That is handled by the WebSession parameter. Note that Cookie header is in fact a Restricted Header, meaning you can just create it like any other regular header.

To store some basic information between different calls to the REST API, I use a Class object. That is easier to handle, and will open perspectives in future episodes of this series.

Class rOpenSdk

PowerShell

1

2

3

4

5

6

7

8

ClassrOpenSdk

{

[String]$Name

[String]$User

[String]$SessionSecret

[String]$Auth

[String]$Uri

}

I use the Verbose option a lot while writing code. So you’ll see my standard “verbosity lines” at the start of each function.

Why?

One might wonder why I would be looking at wrapping these REST API in PowerShell code! More so, since these API can be consumed via native PowerCLI cmdlets (see my earlier note). I did in fact the same before starting this series, and I came up with these (random order) arguments.

Because we can! The fact that these REST API are open and public, make them an attractive alternative for all other available tools.

Open. The wrapper code and the REST API are Open, this in contrast to some of the binary products like PowerCLI. The wrapper code can be version controlled, and we can pull diffs between different versions

Appliance. We can avoid one extra dependency when installing an appliance.

Desired State Configuration (DSC). Same as the Appliance consideration, one less layer to take into account.

PowerShell. Although PostMan, Python, JavaScript… are most probably great tools, it pays to limit the number of tools one is using.

Uniformity. When PowerShell is the preferred tool of automation, it is an advantage to be able consume the REST API with the same tool. Note that if you have PowerCLI installed, you can use the CIS cmdlets (see my remark earlier)

Eco-system. To me it is more and more obvious that REST API are a preferred way to “talk” with many, if eventually not all, of VMware’s products.

Simplicity. The HTTP driven REST communication is simple to manage and control.

Sample Usage

In this first part there are only two functions available, a function to connect, and another to get the list of ESXi nodes in the environment. These two functions allowed me to tackle a number of the basic issues, so future functions should come faster 🙂

These two functions do, currently, not allow for a lot of variation. Open a session, get the list. That’s it.

Sample 1

PowerShell

1

2

3

4

5

6

7

$user='administrator@vsphere.local'

$pswd='HomeLab2017!'

$vcsa='vcsa.local.lab'

Connect-rViServer-User$user-Password$pswd-Server$vcsa-Verbose

Get-rVMHost

In Fiddler2 the connection call is seen as follows. Note the User-Agent is PowerShell 5.1.

Notice how the encoded Authorization header is passed to the REST API.

The REST API returns the session ID. Instead of using a restricted header, this will be passed along through the WebSession parameter on the Invoke-WebRequest cmdlet..

In the subsequent calls to other REST API, the session id will passed.

And of course the result of our REST API call.

As we can notice, the result is returned as a JSON object. In one of the next posts in this series, we will discuss how to convert this to a PowerShell object.