HATEOS and resource navigation in vCloud API

HATEOS stands for Hypermedia as the Engine of Application State. This is a principle or constraint used by the designers when defining resources in RESTful way. Bottom line of this principle is that client needs to know the a fixed or top level URL and be able to access all the necessary resources. Which means every response or resource description should further indicate how to access either related resource or perform certain actions on the resource. Since resources are identified by URL and actions are also represented in the form of URL as we saw in earlier post, the resource description or the HTTP responses should include links or URLs for the navigation purpose.

This is the third level of maturity as described by Richardson. Lets see how vCloud API adheres to this principle.
vCloud API defines a top level URL http://my.vcloud.com/api/versions This URL provides information about all the versions supported by the vCloud Server. For every version supported there is log in URL associated with every version number (if there are more than one :-), which is obviously not the case for the version 1.0)
This is how it looks:
GET http://my.vcloud.com/api/versions
<SupportedVersions xmlns="http://www.vmware.com/vcloud/versions" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/versions http://my.vcloud.com/api/versions/schema/versions.xsd">
    <VersionInfo>
        <Version>1.0</Version>
        <LoginUrl>http://my.vcloud.com/api/v1.0/login</LoginUrl>
        <MediaTypeMapping> ... </MediaTypeMapping>
        ...
    </VersionInfo>
    ....
</SupportedVersions>

Now user needs to fetch the log in URL and perform the log in operation. Which in turn returns a list of 'Reference' to all the Organizations available to this user to access.

<OrgList  ...>
    <Org type="application/vnd.vmware.vcloud.org+xml" name="my-org2" href="https://my.vcloud.com/api/v1.0/org/537058365"/>
    <Org type="application/vnd.vmware.vcloud.org+xml" name="my-org1" href="https://my.vcloud.com/api/v1.0/org/1041520205"/>
</OrgList>
You must have realized by now that the above are refrences/links to the Organization resources. They are not the actual resources. SO we get the URL for the Organization using the 'href' attribute and perfrom the GET operation on it. Notice in following response that the resource provides link to itself as well.

e.g. GET https://my.vcloud.com/api/v1.0/org/537058365
This is of the form https://<server>/api/v1.0/org/{id}. One of the other tenet of HATEOS implemented by vCLoud API is that the URL are opaque. Which means client is discouraged to cache these URL and rely instead on the 'href' and links.

Now lets look into the Organization resource in response to above request
<Org xmlns="http://www.vmware.com/vcloud/v1" name="my-org2" type="application/vnd.vmware.vcloud.org+xml" href="https://my.vcloud.com/api/v1.0/org/537058365" ... >
    <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" name="org2_vdc1" href="https://my.vcloud.com/api/v1.0/vdc/1700638305"/>
    <Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="https://my.vcloud.com/api/v1.0/tasksList/537058365"/>
    <Description>my-org2</Description>
    <FullName>my-org2</FullName>
</Org>

The difference in this response to note is the 'Link' element. This element provides further navigation paths. Specifically how to access the TaskList resource and the vDC resource contained in this Organization. (refer to the UML diagram in my earlier post for detailed relationsships between resources.) Another point to note is the 'rel' attribute. In addition to just giving the navigation paths it also provides the relationsship between this resource and the linked resource using the 'rel' attribute. for example the 'down' indicates containment such that this resource contains the linked resource.

The Link with 'rel' attribute also indicates what actions can be perfromed on this resource. Following Link from the 'Vdc' indicates that we can upload a vApp Template using the URL associated with it.

<Link rel="add" type="application/vnd.vmware.vcloud.uploadVAppTemplateParams+xml" href="https://my.vcloud.com/api/v1.0/vdc/1700638305/action/uploadVAppTemplate"/>
And when it comes to resources like vApp we indicate the available actions as following. This vApp gives out the link to power it off and also indicates what type of relationship (actionin this case) the Link has with the resource.
<VApp ... >
    <Link rel="power:powerOff" href="https://my.vcloud.com/api/v1.0/vApp/vapp-1299560622/power/action/powerOff"/>
    ...
</VApp>

The vCloud API provides only links that are relevant to the curent state of the resource. For example the above link in vApp will only be available if the vApp is in poer on state. If the vApp is powered off then there will be corresponding link to power on operation.

so in conclusion we just saw how the vCloud API adheres to the third level of REST maturity but while doing so we also saw how we can navigate the vCloud resources. Let me promise you one thing, this blog post would be much smaller if I avoid using those XML examples, and you know what it will make your code also very small, readable and maintainable if some one else takes care of those XML and HTTP verbs such as GET/POST. We will see how the SDK released along with the vCloud API can make our life easy in subsequent posts. 

RESTful vCloud API

Many people use REST in many different ways depending on their requirements and more importantly their understanding. One of the favorite topics of blogs is comparison of REST style with SOA and when it comes to OO API and Service oriented API. I will stay clear of opinions but map the vCloud API to the REST pattern. This will help understand why the vCloud API looks the way it is.

Before we get into the details we need to understand the design model and its maturity levels. This job is done by the stalwarts and we will stand on their shoulders to get the better view of vCloud API. Check out these links for more details on the REST Maturity model by Martin Fowler and Leonard Richardson. ( Richardson Maturity Model

Leonard Richardson's explanation) 

Many people call their API; ‘REST API’ when in practice the end points are actually defined as service endpoints rather than resources. They use the XML (or JSON) payload and define the end points very similar to SOAP or XML-RPC style interfaces (e.g. CreateImage, DeregisterImage) . Main point to note these are verbs and not nouns. Those who have done OO programming and defining the objects know that when they read the problem story they underline the nouns to define objects and verbs to define the methods.
When we get into more matured REST API we focus on the nouns to define the resources that are implemented by the server and then expose them to client such that the client now makes requests to the resources rather than using the singular service.
In very simple terms it is almost like calling procedure (services/actions) against operating on objects/resources.

 The vCloud API takes the REST approach by defining resources such as Organization, vDC, vApp, vAppTemplate and so forth.  Client uses HTTP verbs GET, POST, DELETE to inquire the state of the resource (Get the details of the resource), update/create resource and delete the resource. The actual resources and their relationship using the UML diagram.

There is small caveat where the pure REST approach falls short and vCloud API addresses it by introducing ‘action’ verb.  These actions not necessarily create a new resource as one would expect from the generally accepted semantics of HTTP POST operation. As mentioned above one may chose to create URL such as POST …/api/v1.0/poweronvapp which more or less looks like service/operation but vCloud API takes REST like approach where it uses the resource where HTTP verb can be directly used and use the ‘action’ paradigm in conjunction with it. Following examples gives this example.

GET .../api/v1.0/org/<org-id> get organization for given id.

POST .../api/v1.0/catalog/<catalog-id>/catalogItems Create a Catalog Item in given Catalog.

The actions are performed using the POST as follows:  

POST .../api/v1.0/vdc/<vdc-id>/action/instantiateVAppTemplate  : Create/Instantiate new  vApp from given Template (this is sent as part of the request payload, Instantiation Parameters). The action is performed on the vDC which will house the vApp for execution.

POST .../api/v1.0/vApp/<vapp/vm-id>/power/action/powerOn Power on vApp.

The vCloud API handles the long running operations by responding to such actions with the Task resource that represents the tasks in progress. The client can then treat this Task resource like any other resource to enquire the status by doing GET operations.  This resource further provides means (links) to cancel the task (action on the Task resource) and hence does not have any direct POST operations.  Typically the Task is maintained even if it is completed (with success/failure) or canceled and hence not deleted by the user directly.

Hope it gives the general idea of the RESTfullness of the vCloud API. We will visit MOST important feature of the API, which make it Level 3 mature as it uses the HATEOAS (‘Hypertext as the Engine of Application State’) when we discuss how to navigate the resources.