cc06396a16
Update to clouddocs-maven-plugin 2.0.2 Also created parent pom.xml file and updated pom.xml files in v1.0 and v2 dirs to point to parent Changed directory structure slightly to mimic other API dir structures. Added xml:id to sections and chapters in the v1.0 book and the incubation document. Moved shared graphics to figures directory in root directory. Update doc-test.conf for the changes Change-Id: Iae6dddbe39a536c5c71be5919b28f69e588fea43
521 lines
28 KiB
XML
521 lines
28 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<book xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:html="http://www.w3.org/1999/xhtml"
|
|
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
|
|
status="draft" xml:id="apix-proposal">
|
|
<title>OpenStack API Extensions</title>
|
|
<subtitle>An Overview</subtitle>
|
|
<info>
|
|
<copyright>
|
|
<year>2010</year>
|
|
<year>2011</year>
|
|
<holder>Rackspace US, Inc.</holder>
|
|
</copyright>
|
|
<pubdate>2011-06-10</pubdate>
|
|
<legalnotice role="apache2">
|
|
<annotation>
|
|
<remark>Copyright details are filled in by the
|
|
template.</remark>
|
|
</annotation>
|
|
</legalnotice>
|
|
<abstract>
|
|
<para>This document provides an overview of the OpenStack
|
|
API extension mechanism.</para>
|
|
</abstract>
|
|
</info>
|
|
<chapter version="5.0" xml:base="chapters/overview.xml"
|
|
xml:id="overview">
|
|
<title>Overview</title>
|
|
<para>The OpenStack extension mechanism makes it possible to
|
|
add functionality to OpenStack APIs in a manner that
|
|
ensures compatibility with existing clients. This
|
|
capability allows OpenStack operators and vendors to
|
|
provide innovative functionality to their clients and
|
|
provides a means by which new features may be considered
|
|
in upcoming versions of OpenStack APIs.</para>
|
|
<para>This document describes the extension mechanism in
|
|
detail. It provides guidance to API implementors and
|
|
clients on developing and consuming API extensions, it
|
|
describes the rules by which extensions are governed, and
|
|
it describes the process used to promote API extensions to
|
|
new features.</para>
|
|
<warning security="draft">
|
|
<para>Please note that this document is a <emphasis
|
|
role="strong">draft</emphasis>. It is intended to
|
|
give developers an opportunity to provide feedback. If
|
|
you begin implementing against this early access
|
|
specification, please recognize that it is still
|
|
subject to change. Comments, feedback, and bug reports
|
|
are always welcomed; please submit these in the
|
|
webhelp discussion forum at: <link
|
|
xlink:href="http://docs.openstack.org/"
|
|
>http://docs.openstack.org/</link>.</para>
|
|
</warning>
|
|
<section xml:id="audience">
|
|
<title>Intended Audience</title>
|
|
<para>This document is intended for software developers
|
|
who wish either to implement or to consume an
|
|
extensible OpenStack API. It assumes that the reader
|
|
has a general understanding of:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>ReSTful web services</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>HTTP/1.1</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>JSON and/or XML data serialization
|
|
formats</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>At least one OpenStack API: Compute, Object
|
|
Storage, etc.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="organization">
|
|
<title>Organization of this Document</title>
|
|
<variablelist spacing="normal">
|
|
<?dbfo list-presentation="blocks"?>
|
|
<varlistentry>
|
|
<term><xref linkend="Background"/></term>
|
|
<listitem>
|
|
<para>Provides background information on
|
|
OpenStack extensions and the OpenStack
|
|
extension mechanism.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><phrase security="draft">Chapter 3,
|
|
<firstterm>Extensions and
|
|
ReST</firstterm></phrase></term>
|
|
<listitem>
|
|
<para>Describes the specifics of implementing
|
|
and consuming extensions in ReST APIs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><phrase security="draft">Chapter 4,
|
|
<firstterm>Extension Governance and
|
|
Promotion</firstterm></phrase></term>
|
|
<listitem>
|
|
<para>Describes API governance and the process
|
|
by which extensions can be promoted to new
|
|
features in future revisions of an
|
|
API.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><phrase security="draft">Chapter 5,
|
|
<firstterm>Summary</firstterm></phrase></term>
|
|
<listitem>
|
|
<para>Briefly summarizes the benefits of the
|
|
extension mechanism and provides a brief
|
|
overview of how extensions are
|
|
used.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<section xml:id="history">
|
|
<title>Document Change History</title>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr>
|
|
<td align="center" colspan="1">Revision
|
|
Date</td>
|
|
<td align="center" colspan="4">Summary of
|
|
Changes</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1" align="center">June 10,
|
|
2011</td>
|
|
<td colspan="4">
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Initial draft.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="Background" version="5.0"
|
|
xml:base="chapters/background.xml">
|
|
<title>Background</title>
|
|
<para>This chapter provides background information on
|
|
OpenStack extensions and the OpenStack extension
|
|
mechanism. It describes what extensions are, how the
|
|
extension mechanism in OpenStack is related to the OpenGL
|
|
extension mechanism, the differences between extensions
|
|
and versions, the concept of versioning extensions, and
|
|
why extensions are vital when defining a pluggable
|
|
architecture.</para>
|
|
<section xml:id="what-are-extensions">
|
|
<title>What are Extensions?</title>
|
|
<para>OpenStack APIs are defined strictly in two forms: a
|
|
human-readable specification (usually in the form of a
|
|
developer's guide) and a machine-processable WADL.
|
|
These specifications define the core actions,
|
|
capabilities, and media-types of the API. A client can
|
|
always depend on the availability of this
|
|
<firstterm>core API</firstterm> and implementers
|
|
are always required to support it in its entirety.
|
|
Requiring strict adherence to the core API allows
|
|
clients to rely upon a minimal level of functionality
|
|
when interacting with multiple implementations of the
|
|
same API.</para>
|
|
<para>Note that it is quite possible that distinct
|
|
implementations of an OpenStack API exist. First
|
|
because API specifications are released under a free
|
|
license, so anyone may use them to implement a core
|
|
API. Furthermore, the OpenStack implementations
|
|
themselves are released under a free license, making
|
|
it possible to alter the code to create a specialized
|
|
version. Such a specialized implementation could
|
|
remain OpenStack-compatible even if it were to
|
|
implement new features or add new capabilities, but
|
|
only if it made the changes in a manner that ensures
|
|
that a client expecting a core API would continue to
|
|
function normally — this is where extensions come
|
|
in.</para>
|
|
<para>An <firstterm>extension</firstterm> adds
|
|
capabilities to an API beyond those defined in the
|
|
core. The introduction of new features, MIME types,
|
|
actions, states, headers, parameters, and resources
|
|
can all be accomplished by means of extensions to the
|
|
core API. In order for extensions to work, the core
|
|
API must be written in such a manner that it allows
|
|
for extensibility. Additionally, care should be taken
|
|
to ensure that extensions defined by different
|
|
implementers don't clash with one another, that
|
|
clients can detect the presence of extensions via a
|
|
standard method, and that there is a clear promotion
|
|
path at the end of which an extension may become part
|
|
of a future version of the core API. These actions,
|
|
rules, and processes together form the
|
|
<firstterm>extension mechanism</firstterm>. It is
|
|
important that core APIs adhere to this mechanism in
|
|
order to ensure compatibility as new extensions are
|
|
defined. Note also that while a core API may be
|
|
written to allow for extensibility, the extensions
|
|
themselves are never part of the core.</para>
|
|
</section>
|
|
<section xml:id="opengl">
|
|
<title>Relationship to OpenGL</title>
|
|
<para>In the 1990s, OpenGL was developed as a portable
|
|
open graphics library standard. The goal was to
|
|
provide a cross-platform library that could enable
|
|
developers to produce 3D graphics at real time speeds
|
|
(30-120 frames per second). There were several major
|
|
challenges to meeting this goal. In order to be
|
|
considered an open standard, control needed to shift
|
|
from Silicon Graphics (SGI), who originally developed
|
|
OpenGL, to an independent Architecture Review Board
|
|
(ARB) who would be responsible for approving
|
|
specification changes, marking new releases, and
|
|
ensuring conformance testing. Additionally, the
|
|
graphics library itself would need to be designed in a
|
|
manner that would allow the establishment of a stable
|
|
and portable platform for developers. Finally, the
|
|
library would need to garner the support of graphics
|
|
hardware vendors as they would be providing the
|
|
hardware acceleration needed to meet the goal of
|
|
performing at real-time speeds.</para>
|
|
<para>Gaining vendor support is challenging because
|
|
vendors are often in direct competition with one
|
|
another. They differentiate themselves by creating
|
|
innovative new features and by providing niche
|
|
functionality to their users. Thus, OpenGL was faced
|
|
with two competing requirements. On the one hand, it
|
|
needed to abstract away vendor differences in order to
|
|
provide a stable cross-platform environment to
|
|
developers. On the other hand, in order to garner
|
|
vendor support, it needed a method by which vendors
|
|
could differentiate themselves and provide innovative
|
|
new features and niche functionality to their
|
|
users.</para>
|
|
<para>The OpenGL extension mechanism was developed to
|
|
solve these problems. The extension mechanism achieved
|
|
balance between the two requirements by maintaining
|
|
the core specification under the direction of the
|
|
Architecture Review Board while allowing vendors to
|
|
define extensions to the core OpenGL specification.
|
|
The core specification remained uncluttered and
|
|
presented a unified view of common functionality.
|
|
Because extensions were detectable at run time,
|
|
developers could write portable applications that
|
|
could adapt to the hardware on which they were
|
|
running. This method of allowing for an extensible API
|
|
has proven to be a very successful strategy. More than
|
|
500 extensions have been defined in OpenGL's lifetime
|
|
and many vendors, including NVidia, ATI, Apple, IBM,
|
|
and Intel, have participated in the process by
|
|
developing their own custom extensions. Additionally,
|
|
many key innovations (such as vertex and fragment
|
|
shaders) have been developed via the extension process
|
|
and are now part of the core OpenGL API.</para>
|
|
<para>OpenStack, while very different from OpenGL, shares
|
|
many similar goals and faces many of the same
|
|
challenges. OpenStack APIs are designed to be open API
|
|
standards. An important goal is to provide developers
|
|
with a ubiquitous, stable, any-scale cloud development
|
|
platform that abstracts away many of the differences
|
|
between hosting providers and their underlying
|
|
infrastructure (hypervisors, load balancers, etc.). A
|
|
Policy Review Board, similar to OpenGL's Architecture
|
|
Review Board, is responsible for directing development
|
|
of these APIs in a manner that ensures these goals are
|
|
met. As with OpenGL, OpenStack requires support from
|
|
vendors (and cloud providers) in order to be
|
|
successful. As a result, OpenStack APIs also aim to
|
|
provide vendors with a platform which allows them to
|
|
differentiate themselves by providing innovative new
|
|
features and niche functionality to their users.
|
|
Because of these similarities, the OpenStack extension
|
|
mechanism described in this document is modeled after
|
|
the OpenGL extension mechanism. The methods by which
|
|
extensions are defined vary drastically, of course,
|
|
since the nature of the APIs is very different (C
|
|
versus ReST); however, the manner in which extensions
|
|
are documented, the way in which vendors are
|
|
attributed, and the promotion path that an extension
|
|
follows, all borrow heavily from OpenGL.</para>
|
|
</section>
|
|
<section xml:id="extensions_and_versions">
|
|
<title>Extensions and Versions</title>
|
|
<para>Extensions are always interpreted in relation to a
|
|
version of the core API. In other words, from a
|
|
client's perspective, an extension modifies
|
|
<emphasis>a particular version</emphasis> of the
|
|
core API in some way. In reality, an extension may be
|
|
applicable to several versions of an API at once. For
|
|
example, a particular extension may continue to be
|
|
available as a core API moves from one version to
|
|
another. In fact, different implementations may decide
|
|
to include support for an extension at different
|
|
versions. As explained in <phrase security="draft">the
|
|
chapter on "Extension Governance and
|
|
Promotion"</phrase>, when an extension is defined,
|
|
the minimal version of the core API that is required
|
|
to run the extension is specified; implementers are
|
|
free to support the extension in that version or in a
|
|
later version of the core. Note, however, that because
|
|
the extension mechanism allows for promotion, an
|
|
extension in one version of a core API may become a
|
|
standard feature in a later version.</para>
|
|
<note>
|
|
<para>As always, implementers are not required to
|
|
support an extension unless it is promoted to the
|
|
core.</para>
|
|
</note>
|
|
<para>Because several versions of the core API may be
|
|
supported simultaneously, and because each version may
|
|
offer support for a different set of extensions,
|
|
clients must be able to detect what versions and
|
|
extensions are available in a particular deployment.
|
|
Thus, both extensions and versions are query-able.
|
|
Issuing a <command>GET</command> on the base URL
|
|
(<code>/</code>) of the API endpoint returns
|
|
information about what versions are available.
|
|
Similarly, issuing a <command>GET</command> on the
|
|
API's extensions resource
|
|
(<code>/v1.1/extensions</code>) returns
|
|
information about what extensions are available. (See
|
|
<phrase security="draft">the chapter on
|
|
"Extensions and ReST"</phrase> for details of such
|
|
requests.) Note that, since extensions modify a
|
|
particular version of the API, the
|
|
<code>extensions</code> resource itself is always
|
|
accessed at a particular version.</para>
|
|
<para>Backward-compatible changes in an API usually
|
|
require a minor version bump. In an extensible API,
|
|
however, these changes can be brought in as
|
|
extensions. The net effect is that versions change
|
|
infrequently and thus provide a stable platform on
|
|
which to develop. The Policy Review Board (PRB), with
|
|
the help of project team leaders, is responsible for
|
|
ensuring that this stability is maintained by closely
|
|
guarding core API versions. Extensions, however, can
|
|
be developed without the consent or approval of the
|
|
PRB. They can be developed in a completely
|
|
decentralized manner both by individual OpenStack
|
|
developers and by commercial vendors. Because
|
|
extensions can be promoted to standard features, the
|
|
development of new versions can be influenced
|
|
significantly by individual developers and the
|
|
OpenStack client community and is therefore not
|
|
strictly defined by the PRB. In other words, new
|
|
features of a core API may be developed in a bottom-up
|
|
fashion.</para>
|
|
<para>That said, not all extensions are destined to be
|
|
promoted to the next API version. Core APIs always
|
|
deals with core functionality — functionality that is
|
|
supported by all implementations and is applicable in
|
|
common cases. Extensions that deal with niche
|
|
functionality should always remain extensions.</para>
|
|
<para>The table below summarizes the differences between
|
|
versions and extensions.</para>
|
|
<table rules="all">
|
|
<caption>Versions versus Extensions</caption>
|
|
<col width="50%"/>
|
|
<col width="50%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Versions</th>
|
|
<th>Extensions</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><formalpara>
|
|
<title>Rare</title>
|
|
<para>Versions provide a stable
|
|
platform on which to
|
|
develop.</para>
|
|
</formalpara></td>
|
|
<td><formalpara>
|
|
<title>Frequent</title>
|
|
<para>Extensions bring new features to
|
|
the market quickly and in a
|
|
compatible manner.</para>
|
|
</formalpara></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<formalpara>
|
|
<title>Centralized</title>
|
|
<para>Versions are maintained by the
|
|
entity that controls the API Spec:
|
|
the OpenStack Policy Review Board.
|
|
Only the PRB can create a new
|
|
version; only the PRB defines what
|
|
"OpenStack Compute 1.1"
|
|
means.</para>
|
|
</formalpara></td>
|
|
<td><formalpara>
|
|
<title>Decentralized</title>
|
|
<para>Extensions are maintained by
|
|
third parties, including individual
|
|
OpenStack developers and software
|
|
vendors. Anyone can create an
|
|
extension.</para>
|
|
</formalpara></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<formalpara>
|
|
<title>Niche</title>
|
|
<para>Extensions provide specialized
|
|
functionality.</para>
|
|
</formalpara></td>
|
|
<td><formalpara>
|
|
<title>Core</title>
|
|
<para>Versions support core
|
|
functionality.</para>
|
|
</formalpara></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<formalpara>
|
|
<title>Query-able</title>
|
|
<para>Issuing a <command>GET</command>
|
|
on the base URL (<code>/</code>) of
|
|
the API endpoint returns
|
|
information about what versions are
|
|
available.</para>
|
|
</formalpara>
|
|
</td>
|
|
<td>
|
|
<formalpara>
|
|
<title>Query-able</title>
|
|
<para>Issuing a <command>GET</command>
|
|
on the API's extensions resource
|
|
(<code>/v1.1/extensions</code>)
|
|
returns information about what
|
|
extensions are available.</para>
|
|
</formalpara></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<section xml:id="versioning_extensions">
|
|
<title>Versioning Extensions</title>
|
|
<para>There is no explicit versioning mechanism for
|
|
extensions. Nonetheless, there may be cases in which a
|
|
developer decides to update an extension after the
|
|
extension has been released and client support for the
|
|
extension has been established. In these cases, it is
|
|
recommended that a new extension be created. The
|
|
extension may have a name that signifies its
|
|
relationship to the previous version. For example, a
|
|
developer may append an integer to the extension name
|
|
to signify that one extension updates another:
|
|
<code>RAX-PIE2</code> updates
|
|
<code>RAX-PIE</code>.</para>
|
|
<para>Extensions may have dependencies on other
|
|
extensions. For example, <code>RAX-PIE2</code> may
|
|
depend on <code>RAX-PIE</code> and may simply add
|
|
additional capabilities to it. In general,
|
|
dependencies of this kind are discouraged and
|
|
implementers should strive to keep extensions
|
|
independent. That said, extension dependencies allow
|
|
for the possibility of providing updates to existing
|
|
extensions even if the original extension is under the
|
|
control of a different vendor. This is particularly
|
|
useful in cases where an existing extension has good
|
|
client support.</para>
|
|
</section>
|
|
<section xml:id="plug-ability">
|
|
<title>Extensions and Plug-ability</title>
|
|
<para>Core APIs abstract away vendor differences in order
|
|
to provide a cross-platform environment to their
|
|
clients. For example, a client should be able to
|
|
interact with an OpenStack load balancing service
|
|
without worrying about whether the deployment utilizes
|
|
Zeus, Pound, or HAProxy on the backend. OpenStack
|
|
implementations strive to support multiple backends
|
|
out of the box. They do so by employing software
|
|
drivers. Each driver is responsible for communicating
|
|
to a specific backend and is in charge of translating
|
|
core API requests to it.</para>
|
|
<para>The core API contains only those capabilities which
|
|
are applicable to all backends; however, not all
|
|
backends are created equal, with each backend offering
|
|
a distinct set of capabilities. Extensions play a
|
|
critical role in exposing these capabilities to
|
|
clients. This is illustrated below. Here, extensions
|
|
fill in the gap between the common capabilities that
|
|
the core API provides and the unique capabilities of
|
|
the Zeus load balancer. In a sense, one can think of
|
|
extensions as providing front ends to OpenStack
|
|
plug-ins.</para>
|
|
<figure xml:id="core-extensions">
|
|
<title>Extensions and Plug-ability</title>
|
|
<mediaobject>
|
|
<imageobject role="fo">
|
|
<imagedata scale="100"
|
|
fileref="../figures/apix-1service-core-extensions-manybackends.svg"
|
|
format="SVG" align="center"/>
|
|
</imageobject>
|
|
<imageobject role="html">
|
|
<imagedata
|
|
fileref="../figures/apix-1service-core-extensions-manybackends.png"
|
|
format="PNG" align="center"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</figure>
|
|
</section>
|
|
</chapter>
|
|
</book>
|