vCloud Director REST API (vCloud API)

17 Apr 2020 by Simon Greaves

VMware vCloud Director has historically been written with the vCloud API as the primary API mechanism for API modification and access.
The vCloud API is being replaced by the open source vCloud Director OpenAPI, however the vCloud API can still be used to great effect on vCloud Director, up to and including vCD 10.x.

Documentation
vCloud API
vCloud Director OpenAPI

Understanding REST

Whichever API you use, they both use the same format for manipulation, REST. Typically know as being a RESTful format. REST design principals map to ‘CRUD’ operations.  Create, Read, Update and Delete using the HTTP verbs below.

  • To create a resource on the server or begin a task, use POST
    • Power on a vApp task
  • To retrieve a resource or read an object, use GET
  • To change the state of a resource or to update it, use PUT
    • Replace one object with another
  • To remove or delete a resource, use DELETE

Accessing the vCD API — Basic Options

  • Browser — The simplest method to test the vCD API is to point a browser to one of the basic pages: http://vcloud.com/api/versions
  • cURL — Command line tool which supports a number of formats including REST API calls. Is present on most Linux distros
  • REST Client — There are many standalone clients and plugins for browsers useful for making REST API calls

The focus of this article is the REST Client. For my purposes I use Postman, but Chrome and Firefox have API extensions available.
Using our REST Client we need to add a few elements into a request in order to get a valid response.

  1. Our HTTP verb - GET, POST etc., a corresponding URL for the request and body for the request (if required)
  2. Headers
    • Authorization - Some form of credentials
    • Accept - An accepted header format and corresponding response type
      • Version - A common API version to use in the request

Example.
POST https://vcloud.example.com/api/sessions
Authorization: Bearer <Bearer_token_code>
Accept: application/*;version=30.0

This will give us a corresponding status code and an appropriate response.
Lets break these elements down to understand how you can form your own API queries. Starting with the HTTP Verbs.

HTTP Verbs

Operation REST-API-Verb Action Operation Summary
Create POST add Creates a new object
Retrieve GET down Retrieves the representation of an existing object in it’s current state
Update PUT edit Modifies an existing object
Delete DELETE remove Deletes an existing object. If the object is a container (such as a vApp), you must remove all of it’s contents before you can delete it

Status Codes

Primary REST API calls — vCloud Responses

When you make a REST API call, you will get a corresponding response code. You are probably familiar with some of these codes, particularly the 404 (Not found) code when you try and access a website that doesn’t exist.
The type of code you get tells you a lot of information about what about the request is the issue. This is really useful when first using REST codes to help you discover what in your request is the likely causing you issues.
The status code you get in response can vary depending on the request. As an example you won’t get an 202 (Accepted) response for a GET request as 202 is a response for modifications.

Here are some of the most common codes you will find.

Request Success Failure
POST 201 (Created) 400 (Bad Request)
  202 (Accepted) 401 (Not Authorised)
    404 (Not Found)
    406 (Not Acceptable)
GET 200 (0K) 401 (Not Authorised)
    404 (Not Found)
PUT 200 (0K) 400 (Bad Request)
  204 (No Content) 401 (Not Authorised)
    404 (Not Found)
    406 (Not Acceptable)
DELETE 200 (0K) 401 (Not Authorised)
  202 (Accepted) 404 (Not Found)

As you can see, sucessful ones usually are in the 200 range and failures are in the 400+ range.
There are lots of status codes you may find and my hope with this table is to give you a list of all the status code descriptions you are likely to run into with vCD (don’t shoot me if I forget any!).

Status Code Status Description
200 OK The request is valid and was completed. The response includes a document body.
201 Created The request is valid. The requested object was created and can be found at the URL specified in the location header.
202 Accepted The request is valid and a task was created to handle it. This response is usually accompanied by a task element.
204 No Content The request is valid and was completed. The response does not include a body.
400 Bad Request The request body is malformed, incomplete, or otherwise invalid.
401 Unauthorized Login failed or authentication token has expired.
404 Not Found Item not found. Usually indicates a malformed request URL or request body.
405 Method Not Allowed The HTTP method specified in the request is not supported for this object. The verb you are using is not valid for the URI. It can also be the case that the object is not is a valid state for the action. For example deleting an Organization which has not first been disabled.
406 Not Acceptable The resource identified by the request is not capable of generating a response of the type specified in the request’s Accept header.
403 Forbidden Any of:
    One or more objects specified in the request could not be found in the specified container.
    The user is not authenticated or does not have adequate privileges to access one or more Objects specified in the request.
    The user’s session has expired.
409 Conflict The Object state is not compatible with the requested operation.
415 Unsupported Media Type The resource identified by the request does not support a request of the specified Content-Type and HTTP method.
500 Internal Server Error The request was received but could not be completed because of an internal error at the server.
503 Service Unavailable The server is currently unable to handle the request due to a temporary condition such as resource exhaustion or server maintenance. For example the vCD cell start-up has not reached 100%.
504 Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the request URL.

Headers

The other common component of the request is the header used. The common Headers used with vCD are defined as:-

  • HTTP Headers - REST uses HTTP standard headers. They are used to control parameters of the transaction. Generally however they should not contain data.
  • Request Headers — When sending a request to the vCD API, it is required to include a number of request headers depending on the action, for example our credentials.
  • Response Headers — In the reply to our requests we will also receive headers called response headers.

Primary REST API Headers and their Values

Header Function Example Value
Authorization Used to supply login credentials admin@orgname:passwd or
    login token Text and Hex value made up of
  Authorization token x-vmware-vcloud-token-type &
    x-vmware-vcloud-access-token received in reply to our initial log in. (defined below)
    e.g. Bearer HEXCODEababab23313132<truncated>
Accept Content we wish to receive in response. Includes the version of the vCloud Director API we wish to interact with. Application/*+xml;version=30.0
Content-Type Used with POST and PUT requests to define the type of content which we are sending in our body. application/vnd.vmware.vcloud.catalogItem+xml
(Optional) Content-Length The length of the request body in octets (8-bit bytes) Number value, e.g. 1024
(Optional) x-vcloud-authorization Authorization token Hex value, e.g. 2d123d13ae19235ab12dac2eaea316c6

Note x-vcloud-authorization is depreciated in 9.1 and should be replaced with the bearer token in the Authorization header.
Note Login tokens log out sessions after 30 minutes by default, however this can be set in vCD to a higher value.
Note In general, client requests can access objects defined by any version of the vCloud API that is less than or equal to the API version specified in the Accept header.

Initial Log In

Now we know what we need to make a request, lets make an initial login.

  1. Make an API versions request to confirm supported API version. GET http://vcloud.example.com/api/versions
  2. POST a request to the login URL, supplying credentials in the requests Authorization header and state what we will accept in the response.
    POST https://vcloud.example.com/api/sessions
    Authorization: Bearer|Basic|Sign Bearer_token_code|password
    Accept: application/*;version=32.0
  3. Examine the response for the authorization token and copy it in to the Authentication header. Use the contents of X-VMWARE-VCLOUD-TOKEN-TYPE and X-VMWARE-VCLOUD-ACCESS-TOKEN.

Note an asterix is used as a wildcard in the Accept header.
Typically you can use Basic and user name and password for Authorization for first API sessions request in step 2 login to get the token.

Required Fields Walkthrough

To reiterate the login process. When first connecting, use basic authentication POST request on https://vcloudurl.com/api/sessions to get the bearer token and then use that token in subsequent queries.  The first query uses the default option of Basic, subsequent queries use the Bearer token.

Now we have that info, update the next request with this Bearer token shown above in the x-vmware-vcloud-access-token field.
Additionally add the Content-Type header, for example for admin login use
Content-Type: application/vnd.vmware.admin.vcloud+xml

From there you can view the other Content-Type headers you can use with requests. Content-Type headers have the type="NAME"/> variable in the image.
Note As you may have already gathered, vCD API has an admin part for system level administration and a tenant part for tenant level administration. i.e. Don’t expect to be able to modify provider vDC settings from the tenant part!
The body of the response includes clickable links for objects you have rights to access. This will help with navigation within vCD.
The credentials token we receive is valid for 30 minutes by default. If not used, it will expire. If used, it will remain valid. This can be configured within administration settings in vCD.
Now we have the credentials we need we can go ahead an make other vCD API requests. Read on and in the Query section we will walk though an API request together.

Request Headers Further Info

Let’s dig into those headers a bit further to cover some additional ones you may find useful.

Header Information
Accept All requests must include an HTTP Accept header that specifies the type of response that is expected. Three forms of this header are supported:
  Accept: application/*
  Accept: application/vnd.vmware.vcloud.*type*+xml
  Accept: application/*;version=30.0
Accept-Language To specify the language desired in responses, use the Accept-Language request header. To request a response with message strings localized to French, use the following header: Accept-Language: fr
Authorization After you have established a session, you can use the value of the X-VMWARE-VCLOUD-TOKEN-TYPE and X-VMWARE-VCLOUD-ACCESS-TOKEN headers in the Session response to construct an Authorization header for use with subsequent requests.
Content-Type Requests that include a body must include an appropriate HTTP Content-Type header. For example a POST or PUT request that supplies a Catalog item in the request body requires the following Content-Type header:- Content-Type: application/vnd.vmware.vcloud.catalogItem+xml
x-vcloud-authorization This header is returned with the Session response after a successful log-in to the integrated identity provider. As of API version 30, it is deprecated in favor of the X-VMWARE-VCLOUD-ACCESS-TOKEN value returned when you create a Session.
X-VMWARE-VCLOUD-ACCESS-TOKEN Response header. An encoded key used along with the X-VMWARE-VCLOUD-TOKEN-TYPE header, to construct an Authorization header. A replacement for the deprecated x-vcloud-authorization header.
X-VMWARE-VCLOUD-TOKEN-TYPE If a response includes an X-VMWARE-VCLOUD-ACCESS-TOKEN header, it also includes an X-VMWARE-VCLOUD-TOKEN-TYPE header. Example includes Bearer token type.

Navigating the vCD API — Schema Context or View Types

Similar to the tenant/provider approach taken with vCD, there are user elements and admin elements. The admin elements are for the service provider, the user elements are typically for the tenant elements, although you can always have an admin performing user configurations if you so desire. There are also extension elements, for vSphere elements and so forth.

  • User —A URL of the form /api/object/id indicates that any user can access the object if they have the rights.
  • Admin —A URL of the form /api/admin/object/id indicates that org admins and system admins can access the object but an org admin may not have the rights to modify the object, like a network pool or external network.
  • Extension — A URL of the form /api/admin/extension/object/id indicates that system admins can access the object.

Navigating the vCD API — Extension Elements -/api/admin/extension

  • GET https://vcloud.example.com/api/admin/extension to see a list of the available options using system admin credentials.
  • As these are system admin functions they generally refer to the capabilities we have in the System tab of the vCloud Director UI.
    • System level settings: /api/admin/extension/settings
    • vCenter Server list: /api/admin/extension/vimServerReferences
    • Blocking Tasks: /api/admin/extension/blockingTasks

Query Service

The vCloud API query service allows for information on objects within vCloud Director to be retrieved. Queries are read only requests, i.e. GET commands and not PUT or POST.
View a list of available queries with
GET https://vcloud.example.com/api/query

vCD Query Service Definition

Two types of queries are available: Typed and Packaged.

  • Typed queries are ones constructed by the administrator. Typed queries are built in the format /api/query?type=name or https://vcloud.example.com/api/query?[&filter\]
  • Packaged queries have well known URLs, they are predefined and take the basic format /api/object/query

When making queries, you can select what is responded using filters with ?&filter=EXAMPLE-FILTER-NAME appended to the end of the query.

Query Example

As a system admin, list all Org VDC Edges in the environment:
GET https://vcloud.domain.com/api/query?type=edgeGateway&format=records

Filter Example

If you want Edges where the last task performed failed with an error. Then add a filter to the query:
GET https://vcloud.domain.com/api/query?type=edgeGateway&format=records&filter=taskStatus==error

Viewing and Editing Objects

When querying something like the VDC it returns things related to it in <ResourceEntities> brackets.  Such as the vApp info in the below screenshot.

You can then take the href and run subsequent queries like the below.

This then brings us to the vApp view, including the VM info

To modify, go up a level to the VM and click the link to edit the CPU (note it says in the <Link rel="edit" part at the beginning of the line that this is for the editing function.

To perform an edit (change), do a PUT request.
First include the Content-Type header for the PUT request.
Then include the body the change we want to make before clicking send.
Note I recommend you copy over the whole VM information, including the entry you want to change as I have seen it have unexpected consequences if you just copy over the line you want to change. The other values won’t matter applying them as they are already in place and no change will be made, only the changed values are updated, which in this case is the CPU count of the VM.

This should give us back a task element stating we issued a request to change the CPU.

vCD API Troubleshooting

Use https://vcloud.domain.local/api/service_status to check if the service is up.
Useful to test each cell using its HTTP IP address to check load balancer or firewall configurations.
Note Although in our examples we have used /api/versions, calling /api/versions is a non-trivial task and as such it should not be used to determine the status of vCD on a load balancer, /api/server_status status should be used instead.

Common Errors

Access is forbidden

Your session might have timed-out. Try logging in again.
Or you could possibly be missing the authorization headers Make sure to check that you have the proper headers.

Unsupported Media Type

Check the Content-Type header. Be sure to set it correctly (it’s on the ‘Body’ tab).

No valid API version can be selected

Don’t forget to include the Accept header.

Troubleshooting vCD API Calls

All API requests to vCD are logged on the cells which received the call in a requests log file. The log file is located in $CLOUD HOME/logs/ with a name in the format: yyyy_mm dd.request.log. The request logs will also contain requests made by browsers for the vCloud Director Web UI. The format of the log message should give an indication of the source. The Debug logs will not contain individual request information but will contain info and errors on tasks which are invoked.

Also check the Request.log file for access requests. As postman is a Chrome app it shows as a chrome app in the logs.

Tagged with: vCD vCloud API

Keep the conversation going on Twitter!

Reply with Twitter