Bluelock Blog

REST Easy with the vCloud API

June 22, 2010 by John Ellis

The vCloud API is an emerging but already very useful standard for managing virtual infrastructure within a hosted environment. The API itself isn't VMware-centric (although VMware is obviously a huge fan), but instead it was submitted to the Distributed Management Task Force for adoption as an industry standard. The plan is that a single, consistent, platform-independent API could allow a myriad of cloud technologies to effective talk to each other without much fuss or massive message transformation.

The API implementation itself is REST-based, meaning that transactions are stateless and submitted with XML over HTTP. The benefits of using a REST API isn't that it is cutting-edge tech, but instead that it leverages well-established methods for communicating over the Internet. Since REST keeps communication between components simple, poking holes in firewalls and hand-crafting messages can be done very easily.

Let's walk through an example to see just how easy this can be, using only the command line utility curl. Assuming you have a BlueLock vCloud Express account (and, let's face it, all the cool people have vCloud Express accounts) you can simply type:

 curl -u 'your_username:your_password' -v -d "" https://express.bluelock.com/api/v0.8/login 

And voila! The command line parameters you passed along simply tell curl to send your username and password as parameters to a HTTP POST at a given URL.

With the above command you are not only logged in to your vCloud Express account, you also get some advice on what URLs you can try out next:

< Content-Type: application/vnd.vmware.vcloud.orgsList+xml
< set-cookie: vcloud-token=1234567890abcdef; Domain=.bluelock.com; Path=/
< Via: 1.1 express.bluelock.com
< Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8"?>
<OrgList xmlns="http://www.vmware.com/vcloud/v0.8" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.vmware.com/vcloud/v0.8
    https://express3.bluelock.com/api/v0.8/schemas/vcloud/organizationList.xsd">
    <Org type="application/vnd.vmware.vcloud.org+xml" 
        name="your_username" 
        href="https://express3.bluelock.com/api/v0.8/org/31415"/>
</OrgList>

Let's follow one of those links and see what we get. We can use curl to perform an HTTP GET on the link referred to as part of the Org element:

curl https://express3.bluelock.com/api/v0.8/org/824

<error message="Session Key is not found" 
    majorerrorcode="403" 
    minorerrorcode="Bad Request">
</error>

We encountered an error... basically vCloud Express doesn't know who you are. That's where the "stateless" aspect of REST comes into play... subsequent vCloud API calls don't remember who you are.

In the earlier login call we received an HTTP Cookie as part of the response. That "cookie" is a value that reminds the vCloud API of who we are and that we are actually legit, logged-in users. With every subsequent request we send we must also send along the cookie, as in:

curl --cookie "vcloud-token=1234567890abcdef" https://express3.bluelock.com/api/v0.8/org/31415

And now we receive back the response:

<?xml version="1.0" encoding="UTF-8"?>
<Org href="https://express3.bluelock.com/api/v0.8/org/31415" 
    name="your_username" 
    xsi:schemaLocation="http://www.vmware.com/vcloud/v0.8 
    https://express3.bluelock.com/api/v0.8/schemas/vcloud/organization.xsd"
    xmlns="http://www.vmware.com/vcloud/v0.8" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Link rel="down" 
        href="https://express3.bluelock.com/api/v0.8/catalog/0" 
        type="application/vnd.vmware.vcloud.catalog+xml"  
        name="System Catalog"/>
    <Link rel="down" 
        href="https://express3.bluelock.com/api/v0.8/catalog/51413" 
        type="application/vnd.vmware.vcloud.catalog+xml"  
        name="your_username Private Catalog"/>
    <Link rel="down" 
        href="https://express3.bluelock.com/api/v0.8/tasksList/123" 
        type="application/vnd.vmware.vcloud.tasksList+xml"/>
    <Link rel="down" 
        href="https://express3.bluelock.com/api/v0.8/vdc/456" 
        type="application/vnd.vmware.vcloud.vdc+xml"  
        name="testvdc"/>
    <Description></Description>
    <FullName></FullName>
</Org>

More links for us to follow! Awesome!

The full vCloud API specification is available on VMware's site, and the 0.8 version of this API is available on BlueLock vCloud Express. REST easy!

Comments for REST Easy with the vCloud API

blog comments powered by Disqus