Introduction to vCloud API extensions

API extensions in vCloud Director 5.1 is a new feature that allows the cloud provider to extend the vCloud API with new functionality that is not currently implemented within the vCloud API.  API extensions are an open and extensible platform that allows the provider to enrich the services their cloud offers.

There are 12 modules to the API extension framework that provide all of the functionality required to build new services.  By leveraging vCloud Director's existing API capabilities, the service developer can focus on the core business logic of their service without having to deal with the plumbing of the service itself.  API extensions provide facilities for authentication, authorization, localization and other capabilities which we will explore in depth in this article series.

The Service

The Service is the top level concept within an API extension.  The service is implemented by routing HTTP requests and responses to the registered extension service.  The extension service can

Modify the initial API request received by vCloud Director from the client
Modify the response to an API request returned by vCloud Director
Generate a new response message, and return it to the client via vCloud Director

When an API request is receieved for an extension service, the HTTP request is serialized into JSON and published to an AMQP exchange, where the service implementation can then consume the AMQP message, perform it's business logic and return an HTTP response back to vCloud Director as a JSON response message.

In this example of the API extension flow the following takes place.  Note that in this scenario, the REST handler within vCloud Director does not interact with the request, it is handled entirely by the external service.

  1. The client sends a GET request to the API URL they wish to call.
  2. The client is authenticated and authorized and then the extensibility filter matches on the URL called by the client to a regular expression registered with a service extension.  Based on the URL pattern matching, the HTTP request is serialized, and sent as an AMQP message to the exchange defined by the service extension.
  3. The external service implementation consumes the AMQP message, performs the appropriate business logic and returns an HTTP response message back to the AMQP exchange.  The external service could implement really anything that the provider wishes to expose to the tenant.  Storage, Database, Configuration, anything.
  4. The Extensibility filter receives the response message, and sends it back to the client.

In this next example, the external service does not return an HTTP response, but an HTTP request and the request then continues on to the REST handler within vCloud Director.  In this example, our external service can take a request bound for an existing API call within the vCloud API, modify it, and then have it continue on to the REST handler for normal processing.

Defining a service

A service definition is an XML document that contains the following set of properties.  These properties define how the API request will be intercepted by vCloud Director, and how to interact with the service via the AMQP message exchange.

Exchange:  The AMQP exchange the API extension service should publish requests to.
Routing Key:  The AMQP routing key to be set on the message so it can be routed to the apropriate message queue.
Priority:  The order in which the service(s) should process the incoming API request.  Higher priority service extensions process the request first.
API Filters:  One or more URL pattern to match the API call against for routing to the service extension, and associated response content type
URL Pattern:  A regular expression which specifies the URLs that will be handled by the extension service when called by the client.
Response Content Type:  The content type of the HTTP response being sent back by the implementation of the extension service.

The service definition is the minimum requirement for creating a functional API extension within vCloud Director. The service definition uses the HTTP routing module of the API extension framework. In the next article we will go through the process of creating an extension service, registering it with vCloud Director and consuming the new service via the vCloud API.

Add comment

Security code

Joomla templates by a4joomla