First look at the vSphere 6.5 REST API

The other day I stumbled across  a blog series by William Lee who delves deep in to how you use the latest vmware vSphere REST API using PowerCLI. Using the language I know best, Powershell I thought I should give this API I try. I have some experience with API use from before as I often use this to do information exchange between systems, but this is my first experince with vCenter.

This post will cover the very basics on how we authenticate and get a list of all VM’s connected to our vCenter server.

You can explore and test all endpoints by this URL https://vcenter/rest/apiexplorer

To get started I declare two variables for the urls / endpoints we going to use. One for vm’s and one for the session endpoint

$VCBaseUri = "https://host/rest/vcenter/vm"
$SessionUri = "https://host/rest/com/vmware/cis/session"

Based on the credential input from the user we will create a base64 encoded string and create a header for the session endpoint.

#Getting cred and creating auth key
$Cred = Get-Credential
$auth = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($Cred.UserName+':'+$Cred.GetNetworkCredential().Password))
$head = @{
  'Authorization' = "Basic $auth"
}

The $head variable now contains a table with your encoded username and password. We will use this authorization header to create a new session. At first i assumed we could authenticate using basic authentication only but after a little investigation I figured we needed to create a session. vmware has documented the endpoint here

Using our authorization header we connect to the session endpoint and recieves a token that we use in our session header. From now on. All authentication is with this session token.

the key for our token is ‘vmware-api-session-id’

#Creating a Session

$token = (Invoke-RestMethod -Method Post -Headers $head -Uri $SessionUri).Value
$session = @{'vmware-api-session-id' = $token}

Finally you can call the VM endpoint and retrieve all your vms by running the following.

#Calling VM endpoint authenticated with the session

$vms = (Invoke-RestMethod -Uri $VCBaseUri -Headers $session -ContentType 'Application/json').Value

To get a single vm by name, you can filter by appending the uri.

/vm?filter.names=web-w2k12"

Hopefully you will have this output showing all vm’s as objects

My complete script now looks like this.

$VCBaseUri = "https://host/rest/vcenter/vm?filter.names=argaste-web-w2k12"
$SessionUri = "https://host/rest/com/vmware/cis/session"

#Getting cred and creating auth key
$Cred = Get-Credential
$auth = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($Cred.UserName+':'+$Cred.GetNetworkCredential().Password))
$head = @{
  'Authorization' = "Basic $auth"
}

#Creating a Session

$token = (Invoke-RestMethod -Method Post -Headers $head -Uri $SessionUri).Value
$session = @{'vmware-api-session-id' = $token}

#Calling VM endpoint authenticated with the session

$vms = (Invoke-RestMethod -Uri $VCBaseUri -Headers $session -ContentType 'Application/json').Value