Getting started with vCloud Director API

The vCloud Director API is a powerful and easy to use solution for getting information about organizations, VDCs, networking, vApps and eveything else. But that’s not all. You can use it for automate all aspects of vCloud Director, too.

You may think it’s difficult to use the vCloud Director API. But I’m trying to show how easy the usage is and what you can do with this API.

So, let’s get started.

vCloud Director API query tools

You can use the linux command “curl”, the chrome browser app “postman” or any kind of programming language which supports REST. In this post I explain the usage of the vCloud Director API via “postman”.

https://www.getpostman.com/
https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop
https://curl.haxx.se/docs/manpage.html

Headers and credentials to access the vCloud Director API

To use the API you must first set the correct accept header and authenticate yourself. After that you will get a session token. This session token must then be supplied with all other requests in the HTTP header since it is used for authentication for all other requests.

So, the first things are the right accept header and your credentials.

The credentials are the same as for the login in the vCloud Director portal or tenant portal and also the role of the user is enforced for the API access. This means a system administrator can manage all things, an organization admin can manage all org settings and a normal user can manage vApps and so on. It’s the same as for the Web UI.

The credentials are provided base64 encoded via the basic auth header. With this and the accept header you can query /api/sessions to get the authorization token.

But there is something special about the username:

You must append either @system to the username or @orgname. This depends on the role you have. As system administrator you must use @system because your admin user is not bound to a special organization. As org admin or org user you must append your organization name.

For example:

superadmin@system or orgadmin@acme

This is also valid for usernames in email format:

superadmin@domain.tld@system

If you are not correctly authenticated, the following error message appears:


... majorErrorCode="403" message="access denied" minorErrorCode="ACCESS_TO_RESOURCE_IS_FORBIDDEN"/>

Query supported API versions

The initial accept header for your first query is: application/*+xml

With the postman app it should look like this:

vcd-api-versions

Or with the Linux commandline tool ‘curl‘:


curl -i -k -H "Accept:application/*+xml" -X GET https://FQDN/api/versions

When you set this header and make the following query:

GET https://FQDN/api/versions

you will receive a lot of xml data in the body. The last <VersionInfo> node in the xml tree is the latest version you can use. I would recommend using this one.

In my case it’s:

<VersionInfo deprecated="false">
<Version>30.0</Version>
<LoginUrl>https://FQDN/api/sessions</LoginUrl>

Therefore the complete accept header for me is:

application/*+xml;version=30.0

If the accept header is not correctly set, you will see the following error message:


... majorErrorCode="406" message="The request has invalid accept header: . Supported API versions are: [5.5, 5.6, 5.7, 5.8, 5.9, 5.10, 5.11, 5.12, 6.0, 7.0, 9.0, 11.0, 12.0, 13.0, 14.0, 16.0, 17.0, 18.0, 19.0, 20.0, 21.0, 22.0, 23.0, 24.0, 25.0, 26.0, 27.0, 28.0, 29.0, 30.0]" minorErrorCode="NOT_ACCEPTABLE"/>

You just have to do this once, as long as you don’t know the latest supported API version. For future requests you can always use the same accept header string until you upgrade vCloud Director and the API changes.

Get the session token for accessing the vCloud Director API

After you know about the vCloud Director API versions and the accept header, the next step is to get the authorization token for your session. All you need are your vCloud Director credentials and the accept header (see Headers and credentials to access the vCloud Director API).

vCloud Director API

These credentials are base64 encoded and you must submit them in the basic auth header. And don’t forget the accept header we talked about above:

vcd-session-headers

If everything is set correctly, you can query the vCloud Director API with the POST method:

POST https://FQDN/api/sessions

In the header of the response you will find a field named x-vcloud-authorization with the authorization token as value.

See below:vCloud Director API

 

The header x-vcloud-authorization and the provided value must be used for every further query. But it’s a session token. So it’s only valid for a specific timeframe.

With curl it’s the same procedure:


curl -i -k -H "Accept:application/*+xml;version=30.0" -u superadmin@system:YOURPASSWORD -X POST https://FQDN/api/sessions

HTTP/1.1 200 OK
Date: Fri, 13 Jul 2018 18:26:29 GMT
X-VMWARE-VCLOUD-REQUEST-ID: d26eb330-23e1-4ad8-9730-b17674a6cd9e
X-VMWARE-VCLOUD-ACCESS-TOKEN: eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJraXJzY2giLCJpc3MiOiJhOTNjOWRiOS03NDcxLTMxOTItOGQwOS1hOGY3ZWVkYTg1ZjlAY2RjODA5ODMtZGI3Mi00OTNlLWI5MGEtNjUxY2MyOGJlNDRmIiwiZXhwIjoxNTMxNTkyNzg5LCJ2ZXJzaW9uIjoidmNsb3VkXzEuMCIsImp0aSI6IjViMTA5NmFjOGJlNjQ5YmQ5NzZkYWNhNjA0YjIxZGQ3In0.BXzjjCjYiz-kn0H6qVtmhuGB6eawxpjGoOGciufPjKRKKmaEuR45Xx1NhyB79hGWM5lrgaHsAm6uiZ6hmnxiV39s3I0xxMNx2IO-2NlIFQaPcOTjoyemaH_bO5sUN72LOIX6PIoQnA1nPm6G-QGs1sDUGnenGe-snUo0Vdy55Ng62os5YOpBXiVQYMxDiJybcBrAdfj3T-JXmLbvC4Vr2v8vH-sA9yo3rBcRBO6G5ftjmRcMQUGEykZ6vZecCHhDjNZ4SshI-QdiHY-zriHbKi8dMRSZ22nmGUYp75OUfnDbYlbHgm8TWhYm_oo_O-0t3_Q9sXypd688_1Dml6PeLg
X-VMWARE-VCLOUD-TOKEN-TYPE: Bearer
x-vcloud-authorization: 5b1096ac8be649bd976daca604b21dd7
Content-Type: application/vnd.vmware.vcloud.session+xml;version=30.0
X-VMWARE-VCLOUD-REQUEST-EXECUTION-TIME: 323
Connection: close

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

...

 

After all requirements for accessing the vCloud Director API are met, let’s get started with some useful stuff.

Query the vCloud Director API for all organizations

One of the first things you may want to do is retrieving all organizations which exists and get the organization IDs for further queries.

To do this you can use the following query (you will need system administrator privileges):

GET https://FQDN/api/admin/orgs/query

vcd-orgs-query

All organizations are listed in a XML tree in the response body:

org-results

And the command with ‘curl‘ is:


curl -i -k -H "Accept:application/*+xml;version=30.0" -H "x-vcloud-authorization:6fa3d3e2381f44fb8a797aaa0bf69fea" -X GET https://FQDN/api/admin/orgs/query

Every organization has its own OrgRecord with some information. The most important thing is the string at the end of the href attribute, for example: 0464c1ce-f10a-41b1-bbf7-7d42665c8869

This is the organization ID. You can use this ID to request more information about this organization from the vCloud Director API.

Query organizational settings

You can retrieve all information about a specific organization using this query:

GET https://FQDN/api/admin/org/ORG-ID

(replace the string ORG-ID with the correct ID)

Note:
If you look at the URL, you will see that it contains an /admin/ string. You need system administrator rights to use these queries. If you only have the role of Org administrator or Org user, you can simply omit this string and you will see the API for Org users with less information.

Query an organization VDC

It’s the same as for the organization queries. You simply call /api/admin/vdc/ and set the VDC ID to the end. You get the VDC ID from the organization request (see above). The IDs are located in the XML childnode “Vdcs”:

vCloud Director API

So, the whole request looks like (for example):

GET https://FQDN/api/admin/vdc/1a5f611a-a9f2-47e8-bf22-1f030664159d

 

I hope I could give you a short introduction to the topic “vCloud Director API” and make it easier for you to get started. If you want to get an overview of all API functions, take a look at the following section with further information.

Further information

https://blogs.vmware.com/vcloud/2017/10/getting-started-vcloud-director-9-0-api-part-1.html

https://code.vmware.com/apis/287/vcloud#/doc/

https://docs.vmware.com/en/vCloud-Availability-for-vCloud-Director/1.0.1/com.vmware.vcavcd.install.doc/GUID-9A5041C2-0EC7-419E-98D4-1832546751ED.html

Leave a Reply

Your email address will not be published. Required fields are marked *