http_protocol.tex

\documentclass[10pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage[activate={true,nocompatibility},final,tracking=true,kerning=true,spacing=true]{microtype}
\usepackage[plainpages=false,pdfpagelabels,unicode]{hyperref}
\usepackage{fullpage}
\usepackage{graphicx}
\usepackage{fancyhdr}
\usepackage{comment}
\usepackage{tabularx}
\usepackage{occi}
\setlength{\headheight}{13pt}
\pagestyle{fancy}

% default sans-serif
\renewcommand{\familydefault}{\sfdefault}

% no lines for headers and footers
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}

% header
\fancyhf{}
\lhead{GFD-R-P.223}
\rhead{\today}

% footer
\lfoot{occi-wg@ogf.org}
\rfoot{\thepage}

% paragraphs need some space...
\setlength{\parindent}{0pt}
\setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}

% some space between header and text...
\headsep 13pt

\setcounter{secnumdepth}{4}

\begin{document}

% header on first page is different
\thispagestyle{empty}

GFD-R-P.223 \hfill Ralf Nyrén, Independent \\
OCCI-WG \hfill Andy Edmonds, ICCLab, ZHAW \\
\rightline {Thijs Metsch, Intel}
\rightline {Boris Parák, CESNET}
\rightline {February 4, 2013}\\
\rightline {Updated: \today}

\vspace*{0.5in}

\begin{Large}
\textbf{Open Cloud Computing Interface - HTTP Protocol}
\end{Large}

\vspace*{0.5in}

\underline{Status of this Document}

\input{include/status}

This document obsoletes GFD-P-R.185.

\underline{Copyright Notice}

Copyright \copyright Open Grid Forum (2013-2016). All Rights Reserved.

\underline{Trademarks}

OCCI is a trademark of the Open Grid Forum.

\underline{Abstract}

\input{include/abstract}

\newpage
\tableofcontents
\newpage

\section{Introduction}
\label{sec:intro}
\input{include/introduction.tex}

\section{Notational Conventions}
\label{sec:not_conv}
\input{include/notational}

The following terms \cite{rfc3986} are used when referring to URL
components:

\begin{verbatim}
 http://example.com:8080/over/there?action=stop#xyz
 \__/   \______________/\_________/ \_________/ \_/
  |           |            |            |        |
scheme     authority       path        query   fragment
\end{verbatim}

\section{OCCI RESTful HTTP Protocol}

This document specifies the OCCI HTTP Protocol, a RESTful protocol for
communication between OCCI server and OCCI client. The OCCI HTTP Protocol
support multiple different data formats as payload. Data formats are specified
an separate documents.

\section{Namespace}
\label{sec:namspace}

The OCCI HTTP Protocol maps the OCCI Core model into the URL hierarchy by binding
\hl{Kind} and \hl{Mixin} instances to unique URL paths. Such a URL path is called
the {\em location} of the \hl{Kind} or \hl{Mixin}.
A provider is free to choose the {\em location} as long as it is unique
within the service provider's URL namespace.
For example, the \hl{Kind} instance%
\footnote{\tt http://schemas.ogf.org/occi/infrastructure\#compute}
for the \hl{Compute} type may be bound to {\tt /my/occi/api/compute/}.

Whenever a {\em location} is rendered it MUST be either a String or as
defined in RFC6570 \cite{rfc6570}.

A \hl{Kind} instance whose associated type cannot be instantiated MUST NOT be
bound to an URL path. This applies to the \hl{Kind} instance for OCCI Entity
which, according to OCCI Core, cannot be instantiated \cite{occi:core}.

\subsection{Bound and Unbound Paths}

Since a limited set of URL paths are bound to \hl{Kind} and \hl{Mixin}
instances the URL hierarchy consists of both {\em bound} and {\em unbound}
paths.
A bound URL path is the {\em location} of a \hl{Kind} or \hl{Mixin} collection.

An unbound URL path MAY represent the union of all \hl{Kind} and \hl{Mixin}
collection `below' the unbound path.

\section{Headers and Status Codes}
\label{sec:head_stat}

OCCI clients and Servers MUST include a minimum set of mandatory HTTP headers
in each request and response in order to be compliant.
There is also a minimum set of HTTP status codes which MUST be supported by
an implementation of the OCCI HTTP Protocol.

\subsection{Requests Headers}

\begin{description}
\item[Accept] An OCCI client SHOULD specify the media types of the OCCI data
formats it supports in the {\tt Accept} header.
\item[Content-type] If an OCCI client submits payload in a HTTP request
the OCCI client MUST specify the media type of the OCCI data format
in the {\tt Content-type} header.
\item[User-Agent] An OCCI client SHOULD specify the OCCI version
number in the {\tt User-Agent} header. See Section~\ref{subsec:versioning}.
\end{description}

\subsection{Response Headers}

\begin{description}
\item[Accept] An OCCI server SHOULD specify the media types of the OCCI data
formats it supports in the {\tt Accept} header.
\item[Content-type] An OCCI server MUST specify the media type of the OCCI data
format used in an HTTP response.
\item[Server] An OCCI server MUST specify the OCCI version number in the {\tt Server}
header. See Section~\ref{subsec:versioning}.
\end{description}

\subsection{Versioning}
\label{subsec:versioning}
Information about the OCCI version supported by a server implementation
MUST be advertised to a client on each response.
The version field in the response MUST include the value
OCCI/X.Y, where X is the major version number and Y is the minor
version number of the implemented OCCI version. The server
response MUST relay versioning information using the HTTP `Server'
header.

\begin{verbatim}
HTTP/1.1 200 OK
Server: occi-server/1.1 (linux) OCCI/1.2
[...]
\end{verbatim}

Complementing the server-side behavior of an OCCI implementation, a
client SHOULD indicate the version it expects to interact with. In a
client, this information SHOULD be advertised in all requests it issues.
A client request SHOULD relay versioning information in the `User-Agent'
header. The `User-Agent' header MUST include the same value (OCCI/X.Y)
as advertised by the server.

\begin{verbatim}
GET /-/ HTTP/1.1
Host: example.com
User-Agent: occi-client/1.1 (linux) libcurl/7.19.4 OCCI/1.2
[...]
\end{verbatim}

If an OCCI implementation receives a request from a client that
supplies a version number higher than the server supports, the
server MUST respond back to the client with an HTTP status code indicating
that the requested version is not implemented. The \emph{HTTP 501 Not
Implemented} status code MUST be used.

OCCI implementations compliant with this version of the document MUST
use the version string \emph{OCCI/1.2}. Versioning of extensions is
out of scope for this document.

\subsection{Status Codes}
The below list specifies the minimum set of HTTP status codes an OCCI client MUST
understand. An OCCI server MAY return other HTTP status codes but the exact client
behavior in such cases is not specified. The return codes are specified by
\cite{rfc7231} and \cite{rfc7235}.

\begin{description}
\item[200 OK] indicates that the request has succeeded.
\item[201 Created] indicates that the request has been fulfilled and has resulted in one or more new resources being created.
\item[204 No Content] indicates that the server has fulfilled the request but does not need to return a body, relevant headers MAY be present.
\item[400 Bad Request] indicates that the server cannot or will not process the request due to something that is perceived to be a client error
\item[401 Unauthorized] indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.
\item[403 Forbidden] indicates that the server understood the request but refuses to authorize it.
\item[404 Not Found] indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists
\item[405 Method Not Allowed] indicates that the method received in the request-line is known by the origin server but not supported by the target resource.
\item[406 Not Acceptable] indicates that the target resource does not have a current representation that would be acceptable to the user agent
\item[409 Conflict] indicates that the request could not be completed due to a conflict with the current state of the resource
\item[413 Request Entity Too Large] indicates that the request is larger than the server is willing or able to process.
\item[500 Internal Server Error] indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
\item[501 Not Implemented] indicates that the server does not support the functionality required to fulfill the request.
\item[503 Service Unavailable] indicates that the server is currently unable to handle the request due to a temporary overload or maintenance of the server
\end{description}

\section{Pagination}
\label{sec:pagin}

To request partial results of an otherwise large collection message response, pagination SHOULD be used to reduce the load on
both the client and the service provider. This is done in the following manner.

The HTTP GET verb is used when accessing a URL of a collection and the query parameters of {\em page} and {\em number} MUST be used. {\em page} is an indexed
integer that refers to a sub-collection of the requested collection. {\em number} is an integer of items that SHOULD be displayed in one paged response.

% e.g. GET http://host/path/to/collection?page=1;number=100

If {\em number} is too large for the provider to handle (policy, technical limitations) then an \emph{HTTP 413 Request Entity Too Large} response status code MUST be issued to the requesting client.

If there is no more content to be served, the response status code issued to the requesting client MUST be an \emph{HTTP 200 OK} and the response body MUST contain an empty collection.

\section{Filtering}
To request a sub-set of the given collection of \hl{Category} instances or \hl{Entity} sub-type instances, filtering SHOULD be used to
specify the appropriate elements of the collection. Filtering can be performed via the HTTP GET verb on the {\tt Query Interface} and
on various \hl{Entity} sub-type instance collections. The following specification of the filtering mechanism is in the process of being
deprecated and will be replaced by a new mechanism in the next MAJOR release of the standard. In its current form, the availability of
the filtering mechanism is restricted to rendering formats transportable in HTTP headers.

\subsection{Query Interface}
Filtering on the {\tt Query Interface} SHOULD be performed via the HTTP GET verb by including a \hl{Category} instance rendering
in the HTTP request headers. If supported, the response MUST contain only \hl{Category} instances related to the given \hl{Category}
instance. This includes \hl{Kind}s, \hl{Action}s and \hl{Mixin}s.

\subsection{Entity Sub-type Instance Collection}
Filtering on {\tt Entity} sub-type instance collections SHOULD be performed via the HTTP GET verb by including an \hl{Entity} sub-type
instance rendering in the HTTP request headers. If supported, the response MUST contain only \hl{Entity} sub-type instances
with \hl{Attribute} values matching the given \hl{Entity} sub-type instance \hl{Attribute} values.

Filtering \hl{Entity} sub-type instances by assigned \hl{Mixin} instances is implemented via \hl{Mixin}-defined collections.

\section{HTTP Methods Overview}
Table~\ref{tbl:http_verbs} provides a brief overview of the HTTP verb usage. For details, please, see the sections below.

\mytablefloat{
  \label{tbl:http_verbs}
  HTTP Verb Behavior Summary (* = Supports filtering mechanisms)
  } {
  \begin{tabularx}{\textwidth}{p{0.85in} p{0.85in} p{0.85in} p{0.85in} p{0.85in} p{0.85in}}
  \toprule
  Path
  & GET
  & POST
  & POST (\hl{Action})
  & PUT
  & DELETE \\

  \colrule
  \hl{Entity} sub-type instance ({\tt /compute/1}).
  & Retrieve the \hl{Entity} sub-type instance representation.
  & Partial update of the \hl{Entity} sub-type instance.
  & Perform an action on the \hl{Entity} sub-type instance.
  & Create/Update the \hl{Entity} sub-type instance, supplying the full
    representation of the instance.
  & Delete the \hl{Entity} sub-type instance. \\

  \colrule
  \hl{Entity} sub-type instance collection ({\tt /compute/}).
  & Retrieve a collection of \hl{Entity} sub-type instances*.
  & Create a new \hl{Entity} sub-type instance in this collection.
  & Perform actions on a collection of \hl{Entity} sub-type instances.
  & Not Defined.
  & Remove \hl{Entity} sub-type instances from the collection. \\

  \colrule
  \hl{Mixin}-defined \hl{Entity} sub-type instance
    collection ({\tt /my\_stuff/}).
  & Retrieve a collection of \hl{Entity} sub-type instances*.
  & Add an \hl{Entity} sub-type instance to this collection.
  & Perform actions on a collection of \hl{Entity} sub-type instances.
  & Update the collection supplying the full representation
    of the new collection. Including removal and addition of \hl{Entity}
    sub-type instances.
  & Remove \hl{Entity} sub-type instances from the collection. \\

  \colrule
  Query interface ({\tt /-/}).
  & Retrieve \hl{Category} instances*.
  & Add a user-defined \hl{Mixin} instance.
  & Not Defined.
  & Not Defined.
  & Remove a user-defined \hl{Mixin} instance. \\
  \botrule
  \end{tabularx}
}

\section{HTTP Methods Applied to Query Interface}
\label{sec:http_methods_qi}

This section describes HTTP methods used to retrieve and manipulate category instances.  With the help of the query interface it is possible for the client to determine the capabilities of the OCCI implementation it refers to.

The query interface MUST be implemented by all OCCI implementations. It MUST be found at:

\begin{verbatim}
/-/
\end{verbatim}

Implementations MAY also adopt RFC5785~\cite{rfc5785} compliance to advertise this location. Should implementations wish to advertise the Query Interface using the well-known mechanism then they MUST use the following path served from the authority:

\begin{verbatim}
    /.well-known/org/ogf/occi/-/
\end{verbatim}

The renderings for the {\em Category} instance and Category {\em collection} are defined in \cite{occi:text} and \cite{occi:json}.

\subsection{GET Method}

\subsubsection*{Client GET request}
The request MAY include a possible filter rendering.

\subsubsection*{Server GET response}
The response MUST include a category collection rendering.

Upon a successful request a \emph{200 OK} status code MUST be used.

\subsection{PUT Method}

N/A

\subsection{POST Method}

\subsubsection*{Client POST request}
The request MUST include at least one full category instance rendering. It MAY include a category collection rendering.

\subsubsection*{Server POST response}
Upon a successful processing of the request, the \emph{200 OK} status code MUST be returned.

\subsection{DELETE Method}

\subsubsection*{Client DELETE request}
The request MUST include at least one full category instance rendering. It MAY include a category collection rendering.

\subsubsection*{Server DELETE response}
Upon a successful processing of the request, the \emph{200 OK} status code MUST be returned.

\section{HTTP Methods Applied to Entity Instances}
\label{sec:http_methods_ei}

This section describes HTTP methods used to retrieve and manipulate
individual entity instances. An {\em entity instance} refers to an instance
of the OCCI \hl{Resource} type, OCCI \hl{Link} type or a sub-type thereof
\cite{occi:core}.

Each HTTP method described is assumed to operate on an URL referring to
a single element in a collection, a URL such as the following:
\begin{verbatim}
  http://example.com/compute/012d2b48-c334-47f2-9368-557e75249042
\end{verbatim}

The renderings for the {\em entity} and {\em action} instances are defined in \cite{occi:text} and \cite{occi:json}.

\subsection{GET Method}
The HTTP GET method retrieves a rendering of a single (existing) entity instance.

\subsubsection*{Client GET request}
N/A

\subsubsection*{Server GET response}
The response MUST contain an entity instance rendering.

Upon a successful processing of the request, the \emph{200 OK} status code MUST be returned.

\subsection{PUT Method}
The HTTP PUT method either {\em creates} a new or {\em replaces} an existing
entity instance at the specified URL.

\subsubsection{Create}

\paragraph*{Client PUT request}\hfill\\
The request MUST contain an entity instance rendering.

\paragraph*{Server PUT response}\hfill\\
The OCCI implementation MAY return either the \emph{201 Created} or \emph{200 OK} status code. If the OCCI implementation
returns the \emph{200 OK} status code, an entity instance rendering MUST be included as well.
In case of the \emph{201 Created} status code, a location (as defined in RFC7231~\cite{rfc7231}) MUST be included.

\subsubsection{Replace}
Any OCCI \hl{Link}s associated with an existing OCCI \hl{Resource} MUST be left intact.

\paragraph*{Client PUT request}\hfill\\
The request MUST contain an entity instance rendering.

\paragraph*{Server PUT response}\hfill\\
The OCCI implementation MAY return either the \emph{201 Created} or \emph{200 OK} status code. If the OCCI implementation
returns the \emph{200 OK} status code, an entity instance rendering MUST be included as well.
In case of the \emph{201 Created} status code, a location (as defined in RFC7231~\cite{rfc7231}) MUST be included.

\subsection{POST Method}
The HTTP POST method either {\em partially update}s an existing entity instance or triggers
an {\em action} on an existing entity instance.

\subsubsection{Partial Update}

\paragraph*{Client POST request}\hfill\\
The request MUST contain a partial entity instance rendering of the entity instance to be changed.

\paragraph*{Server POST response}\hfill\\
The OCCI implementation MAY return either the \emph{201 Created} or \emph{200 OK} status code. If the OCCI implementation
returns the \emph{200 OK} status code, an entity instance rendering MUST be included as well.
In case of the \emph{201 Created} status code, a location (as defined in RFC7231~\cite{rfc7231}) MUST be included.

\subsubsection{Trigger Action}
Actions are triggered using the HTTP POST verb and by adding a query string to the URL. This query MUST contain
a key-value pair. The key MUST be `action'. The value MUST equal to the \hl{Action}'s term.

\paragraph*{Client POST request}\hfill\\
The request MUST contain an action invocation rendering.

\paragraph*{Server POST response}\hfill\\
The HTTP GET response MAY contain an entity instance rendering or a \hl{Category} instance rendering
depending on the requirements of the specified \hl{Action}.

Upon a successful processing of the request, the \emph{200 OK} status code MUST be returned.

\subsection{DELETE Method}
The HTTP DELETE method deletes an entity instance

\subsubsection*{Client DELETE request}
N/A

\subsubsection*{Server DELETE response}
Upon a successful processing of the request, the \emph{200 OK} or \emph{204 No Content} status
code MUST be returned.

\section{HTTP Methods Applied to Collections}
\label{sec:http_methods_coll}

This section describes the HTTP methods used to retrieve and manipulate
collections. A collection refers to a set of {\em entity instance}s.

Each HTTP method described is assumed to operate
on an URL referring to a collection, an URL such as the following:
\begin{verbatim}
  http://example.com/compute/
\end{verbatim}

The renderings for the entity instance, entity {\em collection} and {\em action}
instances are defined in \cite{occi:text} and \cite{occi:json}.

\subsection{GET Method}
The HTTP GET method retrieves a rendering of a collection of existing entity instances.

\subsubsection*{Client GET request}
The request MAY include a possible filter rendering.

\subsubsection*{Server GET response}
The response MUST include an entity collection rendering.

Upon a successful processing of the request, the \emph{200 OK} status code MUST be returned.

\subsection{PUT Method}
The HTTP PUT is only defined for a collection defined by a \hl{Mixin}. It makes replacing the collection possible.

\subsubsection*{Client PUT request}
The request MUST include an entity collection rendering.

\subsubsection*{Server PUT response}
The response MUST include an entity collection rendering.

Upon a successful processing of the request, the \emph{200 OK} status code MUST be returned.

\subsection{POST Method}
The HTTP POST method is defined for {\em creation} of an entity instance, {\em association}
of entity instance with a \hl{Mixin} and triggering {\em action}s.

\subsubsection{Create Entity Instance}

\paragraph*{Client POST request}\hfill\\
The request MUST include at least one full entity instance rendering.
It MAY include an entity collection rendering.

\paragraph*{Server POST response}\hfill\\
The OCCI implementation MAY return either the \emph{201 Created} or \emph{200 OK} status code. If the OCCI implementation
returns the \emph{200 OK} status code, an entity instance rendering or collection rendering MUST be included as well.
In case of the \emph{201 Created} status code, an entity instance location (as defined in RFC7231~\cite{rfc7231})
or a list of entity instance locations MUST be included.

\subsubsection{Associate Mixin with Entity Instance}
This operation MUST only be available for collections defined by a \hl{Mixin}.

\paragraph*{Client POST request}\hfill\\
The request MUST include an entity collection rendering which require the \hl{Mixin} to be applied.

\paragraph*{Server POST response}\hfill\\
On successful operation the server replies with the \emph{200 OK} HTTP status code it MUST include an entity collection rendering.

\subsubsection{Trigger Action}
Actions are triggered using the HTTP POST verb and by adding a query string to the URL.
This query MUST contain a key-value pair. The key MUST be `action'. The value MUST
equal to the \hl{Action}'s term.

\paragraph*{Client POST request}\hfill\\
The request MUST contain an action invocation rendering.

\paragraph*{Server POST response}\hfill\\
The HTTP GET response MAY contain an entity collection rendering or a \hl{Category} collection rendering
depending on the requirements of the specified \hl{Action}.

Upon a successful processing of the request, the \emph{200 OK} status code MUST be returned.

\subsection{DELETE Method}
The HTTP delete method is used to either {\em delete} all entity instances in
a collection or {\em disassociate} entity instance from a collection defined
by a \hl{Mixin}.

\subsubsection{Delete Entity Instances}

\paragraph*{Client DELETE request}\hfill\\
N/A

\paragraph*{Server DELETE response}\hfill\\
Upon a successful processing of the request, the \emph{200 OK} or \emph{204 No Content} status code MUST be returned.

\subsubsection{Disassociate Mixin from Entity Instances}
This operation MUST only be available for collections defined by a \hl{Mixin}.

\paragraph*{Client DELETE request}\hfill\\
The request MAY include entity collection rendering which requires the \hl{Mixin} to be disassociated.

\paragraph*{Server DELETE response}\hfill\\
Upon a successful processing of the request, the \emph{200 OK} status code MUST be returned.

\section{Security Considerations}
\label{sec:sec_consid}
The OCCI HTTP rendering assumes HTTP or HTTP-related mechanisms for
security. As such, implementations SHOULD support
TLS\footnote{http://datatracker.ietf.org/wg/tls/} for transport layer
security.

Authentication SHOULD be realized by HTTP authentication mechanisms,
namely HTTP Basic or Digest Auth \cite{rfc2617}, with the former as
default. Additional profiles MAY specify other methods and should
ensure that the selected authentication scheme can be rendered over
the HTTP or HTTP-related protocols.

Authorization is not enforced on the protocol level, but SHOULD be
performed by the implementation. For the authorization decision, the
authentication information as provided by the mechanisms described
above MUST be used.

Protection against potential Denial-of-Service scenarios is out of
scope of this document; the OCCI HTTP Protocol specification assumes
cooperative clients that SHOULD use selection and filtering as
provided by the Category mechanism wherever possible. Additional
profiles to this document, however, MAY specifically address such
scenarios; in that case, best practices from the HTTP ecosystem and
appropriate mechanisms as part of the HTTP protocol specification
SHOULD be preferred.

As long as specific extensions of the OCCI Core and Model
specification do not impose additional security requirements on top of the
OCCI Core and Model specification itself, the security considerations
documented above apply to all (existing and future)
extensions. Otherwise, an additional profile to this specification
MUST be provided; this profile MUST express all additional security
considerations using HTTP mechanisms.

\section{Glossary}
\label{sec:glossary}
\input{include/glossary}

\section{Contributors}
\label{sec:contrib}
\input{include/contributors}

\section{Intellectual Property Statement}
\label{sec:ips}
\input{include/ip}

\section{Disclaimer}
\label{sec:disclaim}
\input{include/disclaimer}

\section{Full Copyright Notice}
\label{sec:copy}
\input{include/copyright}

\bibliographystyle{IEEEtran}
\bibliography{references}

\end{document}