Tuesday, 16 April 2019

Getting vCloud Director vApp details through REST API

A colleague of mine asked me to verify the configuration of a vApp by checking the API, to ensure what we were seeing in the GUI was the same as the API.  I have spent a lot of time with postman which is a great tool for making REST calls from a client (either Windows, Mac or Linux are available from https://www.getpostman.com/ - and I should add I am in no means affiliated with them :))

So the two issue I had was that for vCD, most of the API calls need a bearer token rather than basic authentication, and that the API guide refers to a vApp number... but I wasn't sure how to get this.  Performing a GET on /api/objectOfInterest will normally return all available objects in the space, but I guess because vCD is multi-tenant platform, you have to specify very clearly which organization or VDC you're working within).

The steps involved are outlined below:

 Get API Versions
You may already know this if you're familiar with the version of vCD you're using but in case you're not.... there are multiple versions of the API available, which you can check by issuing a GET to https://vcd.domain.local/api/versions using basic authentication:

In my deployment, the latest API version was 30.0.  You can see the authentication is basic using 'administrator@system' for the username, although this could be something different if you have an account with API access. 

Get Bearer token from session
Now that you have the API version, you need to get a bearer token.  vCD doesn't support basic authentication beyond a basic set of calls, but to do anything of interest, you will need to get a bearer token.  

To do this, the API call is https://vcd.domain.local/api/sessions, again with basic authentication, although you will need to specify the header:  Accept : application/*+xml;version=30.0 where 30.0 is whatever you retrieved in the first step

 This will return 'X-VMWARE-VCLOUD-ACCESS-TOKEN' which I have blanked out here... but copy this.  You will need it for all subsequent calls.

Get vApp URL
Now that you have the bearer token, you will need to identify what the URL is for the specific vApp you want to work with...  All of the documentation refers to /api/vApp/vapp-7, which in my opinion is a little misleading as it looks like such a low number that this must be a sequential number issued to vApps when they are created.  This is not the case :)....

Issue the call https://vcd.domain.local/api/extension/vapps/query, only changing your authentication to bearer and pasting the token retrieved from the previous step:

This will return an xml body of all vApps in your environment, so you should be able to find the vApp you need along with its specific URL:

 Horribly formatted because I had to remove customer-specific details!

Now you have that URL, you can issue an API call against that URL to return all data specific to that vApp, as well as individual URLs for returning only specific data (for example, I wanted to return the startup and shutdown timer values for each VM).

Get vApp Specific URL
By hitting the vApp specific URL (https://vcd.domain.local/api/vApp/vapp-{long guid string}/), you will be able to pull specific URLs relevant to the information you require...  For me, the interesting part was the startupSelection URL suffix which returned all values as shown below:

 This is the start, from here you can go through the API guide to do anything you need to do from the API...    Enjoy!