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
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.
No comments:
Post a Comment