Recently, I have been spending some time exploring the vCloud API as a way to get more familiar with the operations within vCloud Director. This has been pretty straightforward as the vCloud API is exposed as a REST API and you can easily interact with it using simple HTTP requests. If you are thinking about trying out the the vCloud API, one very useful document to help you get started is the vCloud API Programming Guide. At first glance, you might think you need to be a programmer to use the vCloud REST API, but you do not.
In this article, I will show you how to start exploring your vCloud Director environment using the vCloud API and some freely available tools. Once you are familiar with the basics, we will then walk through a complete example on how to deploy a new vApp from an existing vApp template in the second part of the article.
vCloud API Fundamentals
Before we get started, there are a few fundamental things that you should know before diving into the vCloud API. This information is documented in the programming guide and will be helpful as you start exploring the API. For more details make sure you review each link below.
Object Taxonomy – You should be familiar with the various objects in vCloud Director such as an Organization or Virtual Datacenter (vDC). If not, there is an overview in the documentation.
Objects, References, and Representations – The vCloud API represents all objects in an XML structure and it contains information about the properties/attributes in the structure.
Links and Link Relations – Link elements are used as way to reference other vCloud objects, actions or relationships within the vCloud API. There is a table in the documentation that lists all the link types.
vCloud API REST Requests – To perform CRUD (Create, Retrieve, Update and Delete) operations using the vCloud API, an HTTP request with the proper input is sent to the server.
vCloud API REST Responses – All vCloud API requests return with HTTP response code and may also include a response body. There is a table in the documentation that lists all response codes and their meanings.
Lastly, the vCloud API is broken into three components:
User (Tenant) API – Consumers of vCloud Director and primarily focuses on vApp provisioning.
Admin (Provider) API – For Cloud Administrators that focuses on platform/tenant administration
Extension API – A Sub-component of Admin API that allows for operations pertaining to the underlying vSphere platform.
The operations that are available in each of these components are documented in the vCloud REST API Reference. You can easily search through the vCloud REST API for a particular operation and the information needed to perform that operation.
Now that we have some background about the vCloud API, I will show you two different tools that you can use to interact with the vCloud API. If you prefer to use a GUI, the RESTClient Firefox Plugin is an option or the RESTclient (http://code.google.com/p/rest-client/) as noted in our programming guide. If you prefer the command line, you can use cURL (http://curl.haxx.se/).
I will quickly demonstrate how to login/logout to a vCloud Director 1.5 environment using the RESTClient Firefox Plugin and cURL.
RESTClient Firefox Plugin Login Example
Step 1 – Launch the RESTClient under Tools->Rest Client:
Step 2 – Next we need to add a HTTP Accept header to specify the version of vCloud Director we are connecting to. The name should be “Accept” and value should be “application/*+xml;version=1.5”:
Step 3 – Now we need to add our login information. The login name will be in the format of username@vcd-organiziation and the password will be the password for that account. When you click ok, the credentials will automatically be encoded and added to the request header:
Step 4 – Now we need to specify the HTTP request method which for a login will be a POST operation. You will also need to specify the URL to your vCloud Director server which is in the format of https://vcd-ip/api/sessions. Finally you can connect by clicking on the send button. If you successfully connected, you should see a an HTTP return code of 200 and a green bar highlighting a successful login:
To view the XML response, you can click on the Response Body tab or the Formatted XML:
Step 5 – To logout, just click on the Logout button
One nice thing about the RESTClient for Firefox is when you use the the “Response Body with Syntax Highlighting”, you can click on any of the links and it will automatically copy it to the top of the method bar. This is helpful so you do not need to manually copy/paste as you are exploring the vCloud API.
cURL Login Example
Step 1 – You will need access to a system with curl installed. You will need to specify the following parameters and the URL to your vCloud Director instance which should be in the form of https://vcd-ip/api/sessions:
-i = Include headers
-k = Performs an “insecure” SSL connection (self signed certs)
-H = Setting the header for the version of vCloud Director (1.5 in this example)
-u = User credentials in the format of [username@org:password]
If you have successfully logged in, you will get an HTTP return code of 200 and the vCloud authorization token like the one highlighted above in red. Make sure you verify the version of vCloud API by looking at the schemaLocation which is highlighted above in green. Using the authorization token return from the previous command (highlighted in red), we would then use that instead of the username/password in all subsequent calls.
Step 2– To logout, we simply perform a DELETE operation and make sure you include the authorization token we retrieve in the previous command:
HTTP/1.1 204 No Content Date: Thu, 23 Feb 2012 18:29:07 GMT Content-Type: application/*+xml;version=1.5 Date: Thu, 23 Feb 2012 18:29:07 GMT
If you have succesfully logged out, you will get a 204 response which from the documentation means that the request was accepted and there is no body response.
Further Exploration
You are now ready to start exploring exploring your vCloud environment by performing “GET” operations (read-only). If you recall earlier, the relationship and actions are expressed as links. In the example, when we first login as a tenant user, will see there are three links: org, query, and entity. We will just focus on exploring the “org” link for now.
Note: You may see other links if you are logging in as a System Administrator of the vCloud instance.
Run the following command to see all Organizations you have access to:
To further explore the details of an organization, you can perform another “GET” operation on the Organization href (https://10.20.181.101/api/org/0d020a29-90de-4000-a0ec-c8a630e65c61) just like before. See what else you can discover!
If you are up for a challenge, see if you can run through the Hello vCloud: A Simplified RESTful Workflow example in the vCloud Programming Guide. If not, you can follow along in the next article as we walk through the complete example together.
Get notification of new blog postings and more by following lamw on Twitter: @lamw
