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”.
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.
superadmin@system or orgadmin@acme
This is also valid for usernames in email format:
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:
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:
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:
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).
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:
If everything is set correctly, you can query the vCloud Director API with the POST method:
In the header of the response you will find a field named x-vcloud-authorization with the authorization token as value.
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):
All organizations are listed in a XML tree in the response body:
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:
(replace the string ORG-ID with the correct ID)
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”:
So, the whole request looks like (for example):
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.