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
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.
create
a resource on the server or begin a task, use POST
read
an object, use GET
update
it, use PUT
delete
a resource, use DELETE
http://vcloud.com/api/versions
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.
GET
, POST
etc., a corresponding URL for the request and body for the request (if required)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.
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 |
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. |
The other common component of the request is the header used. The common Headers used with vCD are defined as:-
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.
Now we know what we need to make a request, lets make an initial login.
GET http://vcloud.example.com/api/versions
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
Bearer|Basic|Sign Bearer_token_code|password
application/*;version=32.0
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.
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.
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. |
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.
/api/object/id
indicates that any user can access the object if they have the rights./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./api/admin/extension/object/id
indicates that system admins can access the object./api/admin/extension
GET https://vcloud.example.com/api/admin/extension
to see a list of the available options using system admin credentials./api/admin/extension/settings
/api/admin/extension/vimServerReferences
/api/admin/extension/blockingTasks
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
Two types of queries are available: Typed and Packaged.
/api/query?type=name
or https://vcloud.example.com/api/query?[&filter\]
/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.
As a system admin, list all Org VDC Edges in the environment:
GET https://vcloud.domain.com/api/query?type=edgeGateway&format=records
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
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.
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.
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.
Check the Content-Type header. Be sure to set it correctly (it’s on the ‘Body’ tab).
Don’t forget to include the Accept header.
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