OCCI Core Specification & Models


The Open Cloud Computing Interface (OCCI) is an open protocol for cloud computing services. It initially targets the infrastructure services (IaaS) layer but its modular design which extends this OCCI Core Specification allows for future targeting of the platform services (PaaS) and application services (SaaS) layers on a future roadmap.

A Representational State Transfer (REST) protocol, it deviates from the underlying HyperText Transfer Protocol (HTTP) only where absolutely necessary and could be described as a "Resource Oriented Architecture (ROA)".RWS Unlike other envelope-based protocols such as Atom and SOAP (which describe complex XML-based structures for data transferred within the HTTP payload, essentially duplicating HTTP's built in header-based metadata functionality), OCCI provides a "clean channel" over which any suitable format can travel without modification or wrapping, using HTTP to its full extent in the way it was intended. OCCI also uses various HTTP verbs in transactions rather than tunneling everything over POST, as was the case with SOAP and the various WS-* protocols. As such all existing HTTP features are available for caching, proxying, gatewaying and other advanced functionality such as partial GETs.

Each resource (i.e. a compute node) is identified by URL(s) and has one or more native representations (i.e. Open Virtualisation Format or OVF) as well as a generic XHTML5 rendering. The latter allows for direct end-user accessibility with well-formed, embedded semantic web markup for consumption by both human and machine clients. As such OCCI simultaneously presents both a machine interface (using native resource renderings) and a user interface (using HTML markup with forms and other web technologies such as Javascript/Ajax) so as to satisfy all common use cases. HTTP content negotiation is used to select between alternative representations and metadata including associations between resources is exposed via HTTP headers (e.g. the Link: and Category: headers).

In this way OCCI is not responsible for the representations themselves, rather it enables users to organise and group resources together to build arbitrarily complex systems of inter-related resources. It relies on existing standards for rendering and does not make any recommendations of one standard format over any other, in the same way as the Internet has many popular image formats.

Servers may require that requests be authenticated using standard HTTP-based authentication mechanisms (including OAuth).OAuth They indicate this requirement by returning HTTP 401 with a WWW-Authenticate header and a suitable challenge (e.g. Basic, Digest, OAuth).

> GET / HTTP/1.1
> Host: cloud.example.com
> 
< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: OAuth realm="http://sp.example.com/"

The client then includes appropriate Authorization headers in its responses:RFC2617

> GET / HTTP/1.1
> Authorization: OAuth realm="http://sp.example.com/",
>                oauth_consumer_key="0685bd9184jfhq22",
>                oauth_token="ad180jjd733klru7",
>                oauth_signature_method="HMAC-SHA1",
>                oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
>                oauth_timestamp="137131200",
>                oauth_nonce="4572616e48616d6d65724c61686176",
>                oauth_version="1.0"

Servers may set and clients may accept cookies in order to maintain authentication state between requests:RFC2109

Set-Cookie: session=4732518c5fe6dbeb8429cdda11d65c3d; domain=.example.com; path=/

Warning

Such sessions should not be used for other purposes (such as server-side state) in line with RESTful principles.

A single entry point is defined by a URL (e.g. http://cloud.example.com/) which may be a collection of resources or some other page as defined by the implementor (e.g. a descriptive web page). Therefore OCCI is fully compatible with any existing web presence such as a marketing site or landing page.

All resources must be addressible by URLs (whose structure is opaque and at the discretion of the implementor) and discoverable via search and/or link traversal from the entry point. Clients should not rely on "rules" to construct URLs, rather learning them from URLs previously retrieved, in line with RESTful principles:

> GET /-/compute/ HTTP/1.1
> Accept: text/uri-list
> 
< HTTP/1.1 200 OK
< Content-type: text/uri-list
<
< /us-east/new-york/node17
< /us-west/san-francisco/node43
< /europe/paris/node38

Clients will typically conduct a GET or HEAD request on the root (/) and discover the category search interface, from which they can learn the supported categories/kinds and retrieve some or all of them. If they know the URL for the resource they wish to interact with (e.g. scripts & cron jobs) then they can bypass the discovery process and manipulate it directly.


Create, Retrieve, Update and Delete (CRUD) operations map to the POST, GET, PUT and DELETE HTTP verbs respectively. HEAD and OPTIONS verbs may be used to retrieve metadata and valid operations without the entity body to improve performance. WebDAV definitions are used for MKCOL, MOVE and COPY.

POST (Create)

The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line.RFC2616

POSTing a representation (e.g. OVF) to a collection (e.g. /compute) will result in a new resource being created (e.g. /compute/123) and returned in the Location: header. POST is also used with HTML form data to trigger verbs (e.g. restart)

GET (Retrieve - Metadata and Entity)

The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI.RFC2616

GETting a resource (e.g. /compute/123) will return a representation of that resource in the most appropriate supported format specified by the client in the Accept header. Otherwise "406 Not Acceptable" will be returned.

PUT (Create or Update)

The PUT method requests that the enclosed entity be stored under the supplied Request-URI.RFC2616

PUTting a representation (e.g. OVF) to a URL (e.g. /compute/123) will result in the resource being created or updated. The URL is known or selected by the client, in contrast to POSTs where the URL is selected by the server.

DELETE (Delete)

The DELETE method requests that the origin server delete the resource identified by the Request-URI.RFC2616

DELETE results in the deletion of the resource (and everything "under" it, as appropriate).

Tip

It is possible to instruct the server to create a resource based on a default configuration (without requiring client support) by doing an empty POST/PUT, specifying Content-type: application/occi (such that the web server knows where to route the request) and specifying the appropriate kind category (such that OCCI knows what to create).

Additionally the following HTTP methods are used:

COPY (Duplicate)

The COPY method creates a duplicate of the source resource identified by the Request-URI, in the destination resource identified by the URI in the Destination header.RFC4918

HEAD (Retrieve - Metadata Only)

The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response.RFC2616

MKCOL (Make Collection)

MKCOL creates a new collection resource at the location specified by the Request-URI.RFC4918

MOVE (Relocate)

The MOVE operation on a non-collection resource is the logical equivalent of a copy (COPY), followed by consistency maintenance processing, followed by a delete of the source, where all three actions are performed in a single operation.RFC4918

OPTIONS

The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI.RFC2616

Tip

Implementors may offer full WebDAV support in order to allow clients to enumerate the entire tree, interact with the resources via standard file managers (e.g. Windows Explorer, Mac OS X Finder), etc.

An action is some process that can be carried out on one or more resources, which may result in a state change and/or the creation of new resource(s).

Each available action for a given resource is indicated via a link with class extension set to action (such that clients can identify actions, including those from third-parties, without deriving meaning from the rel URI).

Link: </us-east/webapp/vm01;start>;
      rel="http://purl.org/occi/action#start";
      class="action";
      title="Start"

Actions defined by this standard reside under the http://purl.org/occi/action# namespace but anyone can define a new action by allocating a URI they control.

An action is triggered via an HTTP POST and depending on the action requested (e.g. resize), parameters may be provided using HTML forms (e.g. application/x-www-form-urlencoded). In the case of HTML-based renderings the actions can therefore be actual HTML forms.

The model defines the objects and how they interrelate. An interface exposes "kinds" which have "attributes" and on which "actions" can be performed. The attributes are exposed as key-value pairs and applicable actions as links, following the REST hypertext constraint (whereby state transitions are defined in-band rather than via rules).

Each category of resources distinguished by some common characteristic or quality is called a kind (e.g. compute, network, storage, queue, application, contact).

Kinds defined by this standard live in the http://purl.org/occi/kind/ namespace but anyone can define a new kind by using a URI they control as the term.

Each resource must specify a kind by way of a category within the scheme http://purl.org/occi/kind#.

Category information allows for flexible organisation of resources into one or more vocabularies (each of which is referred to as a scheme).

The category model was derived from Atom and consists of three attributes:

Category schemes and/or terms defined by this standard reside throughout the http://purl.org/occi/ namespace but anyone can define a new scheme by allocating a URI they control.


Web linking standards for HTTP [LINK] and HTML [HTML5] are used to indicate associations between resources. All formats must support in-band linking including:

  • Link relations (e.g. rel="alternate")

  • Pointers to resources (e.g. href="http://example.com/")

  • Internet media types (e.g. type="text/html")

  • Extensibility (e.g. attribute="value")

Link: </us-east/webapp/build.pdf>;
      rel="related";
      title="Documentation";
      type="application/pdf"

Link relations defined by this standard reside under the http://purl.org/occi/rel namespace but anyone can define a new link relation by allocating a URI they control.

The interface is fully extensible, both via a public peer review process (in order to update the specification itself, usually via registries) and via independent allocation of unique namespaces (in order to cater for vendor-specific enhancements).

Encryption is not required by the specification in order to cater for sites that do not or can not use it (e.g. due to export restrictions, performance reasons, etc.), however SSL/TLS should be used over public networks including the Internet.

in-band

Sending of metadata and control information in the same band, on the same channel, as used for data, for example, by embedding it in HTML. [http://en.wikipedia.org/wiki/In-band]

kind

A category of things distinguished by some common characteristic or quality, for example events, messages, media. [http://wordnetweb.princeton.edu/perl/webwn?s=kind]

out-of-band

Communications which occur outside of a previously established communications method or channel, for example, in HTTP headers. [http://en.wikipedia.org/wiki/Out-of-band_signaling]

type

Internet media (MIME) type.

[OpenSearch] OpenSearch 1.1. http://www.opensearch.org/Specifications/OpenSearch/1.1. A9.com, Inc. (an Amazon company) Clinton DeWitt. Joel Tesler. Michael Fagan. Joe Gregorio. Aaron Sauve. James Snell. 2009.

[RFC4287] RFC 4287 - The Atom Syndication Format. http://tools.ietf.org/html/rfc4287. Robert Syre. Mark Nottingham. Internet Engineering Task Force (IETF) 2005-12.

[HTML5] HTML 5. http://www.w3.org/TR/html5/. Ian Hickson. David Hyatt. World Wide Web Consortium (W3C) 2009-08-25.

[OAuth] OAuth. http://oauth.net/core/1.0. OAuth Core Workgroup . 2007-12-04.

[RWS] RESTful Web Services. http://oreilly.com/catalog/9780596529260/. 9780596529260. O'Reilly Media Leonard Richardson. Sam Ruby. 2007-05.

[LINK] Web Linking. http://tools.ietf.org/html/draft-nottingham-http-link-header. Internet Engineering Task Force (IETF) Mark Nottingham. 2009-07-12.

[CATEGORY] Web Categories. http://tools.ietf.org/html/draft-johnston-http-category-header. Internet Engineering Task Force (IETF) Sam Johnston. 2009-07-1.