openstack-attic/compute-api
Code Issues Proposed changes

Updated title of Compute Dev Guide to add extensions

Browse Source 
bug: #1156827

Change-Id: I8d1bc5cd81346a617c69424e0cee8858b4d80b37
author: Diane Fleming
This commit is contained in:
Diane Fleming
2013-04-27 10:08:43 -05:00
parent 3c1d1e60b1
commit ac34e393fa
11 changed files with 387 additions and 407 deletions
Download Patch File Download Diff File Expand all files Collapse all files

398
openstack-compute-api-2/src/os-compute-devguide.xml
View File

@@ -34,8 +34,10 @@
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="os-cs-devguide">
<title>OpenStack Compute Developer Guide</title>
<titleabbrev>OpenStack Compute Dev Guide</titleabbrev>
<title>OpenStack Compute and Extensions Developer Guide</title>
<?rax title.font.size="32px"?>
<titleabbrev>OpenStack Compute and Extensions Dev
Guide</titleabbrev>
<info>
<author>
<personname>
@@ -43,7 +45,7 @@
<surname/>
</personname>
<affiliation>
<orgname>OpenStack LLC</orgname>
<orgname>OpenStack Foundation</orgname>
</affiliation>
</author>
<copyright>
@@ -55,8 +57,8 @@
<holder>OpenStack Foundation</holder>
</copyright>
<releaseinfo>API v2</releaseinfo>
<productname>OpenStack Compute</productname>
<pubdate>2012-05-30</pubdate>
<productname>OpenStack Compute and Extensions</productname>
<pubdate/>
<legalnotice role="apache2">
<annotation>
<remark>Copyright details are filled in by the
@@ -70,6 +72,19 @@
(<abbrev>API</abbrev>). </para>
</abstract>
<revhistory>
<revision>
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
<date>2013-04-27</date>
<revdescription>
<itemizedlist>
<listitem>
<para>Changed title of this book to
reflect that it contains Compute
extensions.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
<date>2013-04-17</date>
@@ -77,8 +92,9 @@
<itemizedlist>
<listitem>
<para>Added <xref
linkend="ext-os-admin-actions"
/> to document the server admin actions extension.</para>
linkend="ext-os-admin-actions"/> to
document the server admin actions
extension.</para>
</listitem>
</itemizedlist>
</revdescription>
@@ -171,26 +187,26 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para> Added <parameter>limit</parameter>
<para>Added <parameter>limit</parameter>
and <parameter>marker</parameter>
parameters to list operations. </para>
</listitem>
<listitem>
<para> The rebuild action behaves just
like create: an imageRef is used and a
<para>The rebuild action behaves just like
create: an imageRef is used and a
password may be specified. </para>
</listitem>
<listitem>
<para> Added tenant and user_id attributes
<para>Added tenant and user_id attributes
to server and image. </para>
</listitem>
<listitem>
<para> Added vcpus attribute to flavors.
<para>Added vcpus attribute to flavors.
</para>
</listitem>
<listitem>
<para> We now use a flavorRef in the
resize action. </para>
<para>We now use a flavorRef in the resize
action. </para>
</listitem>
</itemizedlist>
</revdescription>
@@ -200,78 +216,78 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para> Added missing response examples for
<para>Added missing response examples for
server update. </para>
</listitem>
<listitem>
<para> Ensure consistent HTTP status codes
<para>Ensure consistent HTTP status codes
for all resources. </para>
</listitem>
<listitem>
<para> Clarifications on setting and
<para>Clarifications on setting and
changing a server password. </para>
</listitem>
<listitem>
<para> Minor updates to metadata section
<para>Minor updates to metadata section
for clarity. </para>
</listitem>
<listitem>
<para> Discuss alternate links. </para>
<para>Discuss alternate links. </para>
</listitem>
<listitem>
<para> Removed version number from compute
<para>Removed version number from compute
media types &mdash; use a media type
parameter instead. </para>
</listitem>
<listitem>
<para> Bought back the flavorRef and
<para>Bought back the flavorRef and
imageRef server attributes these are
now only used when creating a server.
</para>
</listitem>
<listitem>
<para> Made the create image operation a
<para>Made the create image operation a
server action. </para>
</listitem>
<listitem>
<para> Added minDisk and minRam filters to
<para>Added minDisk and minRam filters to
flavor lists. </para>
</listitem>
<listitem>
<para> Added minDisk and minRam attributes
<para>Added minDisk and minRam attributes
to images. </para>
</listitem>
<listitem>
<para> Asynchronous faults may now contain
<para>Asynchronous faults may now contain
a timestamp. </para>
</listitem>
<listitem>
<para> Changes-since request returns an
<para>Changes-since request returns an
empty list rather than a 304. </para>
</listitem>
<listitem>
<para> Added DELETED image status. </para>
<para>Added DELETED image status. </para>
</listitem>
<listitem>
<para> Fix content length in <xref
<para>Fix content length in <xref
linkend="ImageCreateFullResponse"
/>. </para>
</listitem>
<listitem>
<para> Fixed bad request error code in
<para>Fixed bad request error code in
<xref
linkend="Server_Passwords-d1e2510"
/>. </para>
</listitem>
<listitem>
<para> Compact image, server, and flavor
<para>Compact image, server, and flavor
lists should contain IDs, names, and
links (Any kind of link may be
included &mdash; not just self links).
</para>
</listitem>
<listitem>
<para> Changed metadata URI from .../meta
<para>Changed metadata URI from .../meta
to .../metadata for consistency.
</para>
</listitem>
@@ -283,7 +299,7 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para> Renamed Primary IP to Access IP.
<para>Renamed Primary IP to Access IP.
</para>
</listitem>
</itemizedlist>
@@ -294,73 +310,72 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para> Many minor updates based on
<para>Many minor updates based on
community feedback. </para>
</listitem>
<listitem>
<para> Removed sections on Content
<para>Removed sections on Content
Compression, Persistent Connections,
and Caching &mdash; these are operator
specific. Added section on HTTP.
</para>
</listitem>
<listitem>
<para> A Location header is returned when
<para>A Location header is returned when
creating servers/images. </para>
</listitem>
<listitem>
<para> Added filters to collection of
<para>Added filters to collection of
Image, Servers, and Flavors. </para>
</listitem>
<listitem>
<para> Added asynchronous faults. </para>
<para>Added asynchronous faults. </para>
</listitem>
<listitem>
<para> Updates to links and references.
<para>Updates to links and references.
Remove serverRef, imageRef, and
flavorRef and instead embed one entity
in another to provide links. </para>
</listitem>
<listitem>
<para> Added primary IP addresses. </para>
<para>Added primary IP addresses. </para>
</listitem>
<listitem>
<para> Added forbidden fault. </para>
<para>Added forbidden fault. </para>
</listitem>
<listitem>
<para> We now use a single bookmark link
<para>We now use a single bookmark link
per entity regardless of mimetype.
</para>
</listitem>
<listitem>
<para> Collections are now sorted by
create time. </para>
<para>Collections are now sorted by create
time. </para>
</listitem>
<listitem>
<para> Previous links are no longer
<para>Previous links are no longer
required. </para>
</listitem>
<listitem>
<para> Added the ability to create or
<para>Added the ability to create or
update multiple metadata items
simultaneously. </para>
</listitem>
<listitem>
<para> Minor cleanups to server and image
<para>Minor cleanups to server and image
state machine. </para>
</listitem>
<listitem>
<para> Update to JSON collection format.
<para>Update to JSON collection format.
</para>
</listitem>
<listitem>
<para> Replace integer IDs with UUIDs.
<para>Replace integer IDs with UUIDs.
</para>
</listitem>
<listitem>
<para> Removed affinityID, this will
likely come in as an extension.
</para>
<para>Removed affinityID, this will likely
come in as an extension. </para>
</listitem>
</itemizedlist>
</revdescription>
@@ -370,7 +385,7 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para> Some minor cleanups in preparation
<para>Some minor cleanups in preparation
for OpenStack Summit discussion.
</para>
</listitem>
@@ -382,32 +397,32 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para> Many minor updates based on
<para>Many minor updates based on
community feedback. </para>
</listitem>
<listitem>
<para> Updates to resource linking and
<para>Updates to resource linking and
references. </para>
</listitem>
<listitem>
<para> Better description of paginated
<para>Better description of paginated
collections. </para>
</listitem>
<listitem>
<para> Metadata supported in servers and
<para>Metadata supported in servers and
images. </para>
</listitem>
<listitem>
<para> Dropped support for shared IP
<para>Dropped support for shared IP
groups. </para>
</listitem>
<listitem>
<para> IPs organized by network id, vs
<para>IPs organized by network id, vs
simply having public and private IPs.
</para>
</listitem>
<listitem>
<para> Generalized affinity id. </para>
<para>Generalized affinity id. </para>
</listitem>
</itemizedlist>
</revdescription>
@@ -417,7 +432,7 @@
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para> Initial release. </para>
<para>Initial release. </para>
</listitem>
</itemizedlist>
</revdescription>
@@ -426,8 +441,8 @@
</info>
<chapter xml:id="Overview-d1e71">
<title>Overview</title>
<preface xml:id="preface">
<title>Preface</title>
<para>OpenStack Compute is a compute service that provides
server capacity in the cloud. Compute Servers come in
different flavors of memory, cores, disk space, and CPU,
@@ -477,69 +492,11 @@
xlink:href="http://docs.openstack.org">
http://docs.openstack.org</link>. </para>
</section>
</chapter>
<chapter xml:id="Concepts-d1e369">
<?dbhtml stop-chunking?>
<title>Concepts</title>
<para> To use the OpenStack Compute API effectively, you
should understand several key concepts: </para>
<section xml:id="Server-d1e379">
<title>Server</title>
<para> A server is a virtual machine instance in the
compute system. Flavor and image are requisite
elements when creating a server. </para>
</section>
<section xml:id="Flavor-d1e388">
<title>Flavor</title>
<para> A flavor is an available hardware configuration for
a server. Each flavor has a unique combination of disk
space, memory capacity and priority for CPU time.
</para>
</section>
<section xml:id="Image-d1e398">
<title>Image</title>
<para> An image is a collection of files used to create or
rebuild a server. Operators provide a number of
pre-built OS images by default. You may also create
custom images from cloud servers you have launched.
These custom images are useful for backup purposes or
for producing “gold” server images if you plan to
deploy a particular server configuration frequently.
</para>
</section>
<section xml:id="Reboot-d1e407">
<title>Reboot</title>
<para> The reboot function allows for either a soft or
hard reboot of a server. With a soft reboot, the
operating system is signaled to restart, which allows
for a graceful shutdown of all processes. A hard
reboot is the equivalent of power cycling the server.
The virtualization platform should ensure that the
reboot action has completed successfully even in cases
in which the underlying domain/vm is paused or
halted/stopped. </para>
</section>
<section xml:id="Rebuild-d1e416">
<title>Rebuild</title>
<para> The rebuild function removes all data on the server
and replaces it with the specified image. Server ID
and IP addresses remain the same. </para>
</section>
<section xml:id="Resize-d1e425">
<title>Resize</title>
<para> The resize function converts an existing server to
a different flavor, in essence, scaling the server up
or down. The original server is saved for a period of
time to allow rollback if there is a problem. All
resizes should be tested and explicitly confirmed, at
which time the original server is removed. All resizes
are automatically confirmed after 24 hours if they are
not confirmed or reverted. </para>
</section>
</chapter>
</preface>
<chapter xml:id="General_API_Information-d1e436">
<title>General API Information</title>
<para> The OpenStack Compute API is defined as a ReSTful HTTP
<para>The OpenStack Compute API is defined as a ReSTful HTTP
service. The API takes advantage of all aspects of the
HTTP protocol (methods, URIs, media types, response codes,
etc.) and providers are free to use existing features of
@@ -551,12 +508,13 @@
&GET; requests using ETags, or they may send a redirect in
response to a &GET; request. Clients should be written to
account for these differences. </para>
<para> Providers may return information identifying requests
in HTTP response headers, for example, to facilitate
<para>Providers can return information identifying requests in
HTTP response headers, for example, to facilitate
communication between the provider and client users. </para>
<xi:include href="section_concepts.xml"/>
<section xml:id="Authentication-d1e444">
<title>Authentication</title>
<para> Each HTTP request against the OpenStack Compute
<para>Each HTTP request against the OpenStack Compute
system requires the inclusion of specific
authentication credentials. A single deployment may
support multiple authentication schemes (OAuth, Basic
@@ -565,27 +523,25 @@
system. Please contact your provider to determine the
best way to authenticate against this API. </para>
<note>
<para> Some authentication schemes may require that
the API operate using SSL over HTTP (HTTPS).
</para>
<para>Some authentication schemes may require that the
API operate using SSL over HTTP (HTTPS). </para>
</note>
</section>
<section xml:id="Request_Response_Types-d1e459">
<title>Request/Response Types</title>
<para> The OpenStack Compute API supports both the JSON
and XML data serialization formats. The request format
is specified using the <code>Content-Type</code>
header and is required for operations that have a
request body. The response format can be specified in
requests using either the <code>Accept</code> header
or adding an .xml or .json extension to the request
URI. Note that it is possible for a response to be
serialized using a format different from the request
(see example below). If no response format is
specified, JSON is the default. If conflicting formats
are specified using both an <code>Accept</code> header
and a query extension, the query extension takes
precedence. </para>
<para>The OpenStack Compute API supports both the JSON and
XML data serialization formats. The request format is
specified using the <code>Content-Type</code> header
and is required for operations that have a request
body. The response format can be specified in requests
using either the <code>Accept</code> header or adding
an .xml or .json extension to the request URI. Note
that it is possible for a response to be serialized
using a format different from the request (see example
below). If no response format is specified, JSON is
the default. If conflicting formats are specified
using both an <code>Accept</code> header and a query
extension, the query extension takes precedence. </para>
<table rules="all">
<caption>JSON and XML Response Formats</caption>
<thead>
@@ -635,7 +591,7 @@ Content-Type: application/xml; charset=UTF-8
</literallayout>
<programlisting language="xml"><?db-font-size 80%?><xi:include href="samples/server-post-resp.xml" parse="text"/></programlisting>
</example>
<para> Notice, in the above example, that the content type
<para>Notice, in the above example, that the content type
is set to application/json but it asks for an
application/xml response with the <code>Accept</code>
header. An alternative method of achieving the same
@@ -656,7 +612,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?>
<section xml:id="LinksReferences">
<title>Links and References</title>
<para> Often resources need to refer to other resources.
<para>Often resources need to refer to other resources.
For example, when creating a server, you must specify
the image from which to build the server. You can
specify the image by providing an ID or a URL to a
@@ -729,7 +685,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?>
<section xml:id="Paginated_Collections-d1e664">
<title>Paginated Collections</title>
<para> To reduce load on the service, list operations will
<para>To reduce load on the service, list operations will
return a maximum number of items at a time. The
maximum number of items returned is determined by the
compute provider. To navigate the collection, the
@@ -748,10 +704,10 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
(<errorcode>413</errorcode>) fault may be thrown.
A marker with an invalid ID will return a badRequest
(<errorcode>400</errorcode>) fault. </para>
<para> For convenience, collections are required to
contain atom "next" links. They may optionally also
contain "previous" links. The last page in the list
will not contain a "next" link. The following examples
<para>For convenience, collections are required to contain
atom "next" links. They may optionally also contain
"previous" links. The last page in the list will not
contain a "next" link. The following examples
illustrate three pages in a collection of images. The
first page was retrieved via a &GET; to
http://servers.api.openstack.org/v2/1234/images?limit=1.
@@ -764,9 +720,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?>
<example>
<title>Images Collection, First Page: XML</title>
<programlisting language="xml">
<xi:include href="samples/images-page1.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/images-page1.xml" parse="text"/></programlisting>
</example>
<example>
<title>Images Collection, First Page: JSON</title>
@@ -775,9 +729,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?>
<example>
<title>Images Collection, Second Page: XML</title>
<programlisting language="xml">
<xi:include href="samples/images-page2.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/images-page2.xml" parse="text"/></programlisting>
</example>
<example>
<title>Images Collection, Second Page: JSON</title>
@@ -794,7 +746,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<title>Images Collection, Last Page: JSON</title>
<programlisting language="json"><xi:include href="samples/images-page3.json" parse="text"/></programlisting>
</example>
<para> In JSON, members in a paginated collection are
<para>In JSON, members in a paginated collection are
stored in a JSON array named after the collection. A
JSON object may also be used to hold members in cases
where using an associative array is more practical.
@@ -828,7 +780,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<title>Efficient Polling with the
<parameter>Changes-Since</parameter>
Parameter</title>
<para> The ReST API allows you to poll for the status of
<para>The ReST API allows you to poll for the status of
certain operations by performing a &GET; on various
elements. Rather than re-downloading and re-parsing
the full status at each polling interval, your ReST
@@ -853,7 +805,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
https://api.servers.openstack.org/v2/224532/servers?<parameter>changes-since</parameter>=2011-01-24T17:08Z
would list all servers that have changed since Mon, 24
Jan 2011 17:08:00 UTC. </para>
<para> To allow clients to keep track of changes, the
<para>To allow clients to keep track of changes, the
changes-since filter displays items that have been
<emphasis>recently</emphasis> deleted. Both images
and servers contain a <code>DELETED</code> status that
@@ -866,7 +818,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?>
<section xml:id="Limits-d1e846">
<title>Limits</title>
<para> Accounts may be pre-configured with a set of
<para>Accounts may be pre-configured with a set of
thresholds (or limits) to manage capacity and prevent
abuse of the system. The system recognizes two kinds
of limits: <firstterm>rate limits</firstterm> and
@@ -882,14 +834,14 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
too low. </para>
<section xml:id="Rate_Limits-d1e862">
<title>Rate Limits</title>
<para> Rate limits are specified in terms of both a
<para>Rate limits are specified in terms of both a
human-readable wild-card URI and a
machine-processable regular expression. The
human-readable limit is intended for displaying in
graphical user interfaces. The machine-processable
form is intended to be used directly by client
applications. </para>
<para> The regular expression boundary matcher "^" for
<para>The regular expression boundary matcher "^" for
the rate limit takes effect after the root URI
path. For example, the regular expression
^/servers would match the bolded portion of the
@@ -939,8 +891,8 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
</tr>
</tbody>
</table>
<para> Rate limits are applied in order relative to
the verb, going from least to most specific. For
<para>Rate limits are applied in order relative to the
verb, going from least to most specific. For
example, although the threshold for &POST; to
*/servers is 50 per day, one cannot &POST; to
*/servers more than 10 times within a single
@@ -956,7 +908,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?>
<section xml:id="Absolute_Limits-d1e994">
<title>Absolute Limits</title>
<para> Absolute limits are specified as name/value
<para>Absolute limits are specified as name/value
pairs. The name of the absolute limit uniquely
identifies the limit within a deployment. Please
consult your provider for an exhaustive list of
@@ -1013,7 +965,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?>
<section xml:id="ProgramaticLimits">
<title>Determining Limits Programmatically</title>
<para> Applications can programmatically determine
<para>Applications can programmatically determine
current account limits using the /limits URI as
follows: </para>
<informaltable rules="all">
@@ -1093,22 +1045,20 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
</literallayout>
</example>
<note>
<para> The MIME type versioning approach allows for
the creating of permanent links, because the
version scheme is not specified in the URI path:
<para>The MIME type versioning approach allows for the
creating of permanent links, because the version
scheme is not specified in the URI path:
https://api.servers.openstack.org/224532/servers/123.
</para>
</note>
<?hard-pagebreak?>
<para> If a request is made without a version specified in
<para>If a request is made without a version specified in
the URI or via HTTP headers, then a multiple-choices
response (<returnvalue>300</returnvalue>) will follow
providing links and MIME types to available versions. </para>
<example>
<title>Multiple Choices Response: XML</title>
<programlisting language="xml">
<xi:include href="samples/choices.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/choices.xml" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<example>
@@ -1116,7 +1066,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/choices.json" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<para> New features and functionality that do not break
<para>New features and functionality that do not break
API-compatibility will be introduced in the current
version of the API as extensions (see below) and the
URI and MIME types will remain unchanged. Features or
@@ -1128,7 +1078,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Providers should work with developers and partners to
ensure there is adequate time to migrate to the new
version before deprecated versions are discontinued. </para>
<para> Your application can programmatically determine
<para>Your application can programmatically determine
available API versions by performing a &GET; on the
root URL (i.e. with the version and everything to the
right of it truncated) returned from the
@@ -1159,25 +1109,21 @@ Host: servers.api.openstack.org
body.</para>
<example>
<title>Versions List Response: XML</title>
<programlisting language="xml">
<xi:include href="samples/versions.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/versions.xml" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<example>
<title>Versions List Response: Atom</title>
<programlisting language="xml">
<xi:include href="samples/versions-atom.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/versions-atom.xml" parse="text"/></programlisting>
</example>
<example>
<title>Versions List Response: JSON</title>
<programlisting language="json"><?db-font-size 80% ?><xi:include href="samples/versions.json" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<para> You can also obtain additional information about a
<para>You can also obtain additional information about a
specific version by performing a &GET; on the base
version URL (e.g.
version URL (such as,
https://servers.api.openstack.org/v2/). Version
request URLs should always end with a trailing slash
(/). If the slash is omitted, the server may respond
@@ -1213,23 +1159,19 @@ Host: servers.api.openstack.org/v2/
body</para>
<example>
<title>Version Details Response: XML</title>
<programlisting language="xml">
<xi:include href="samples/version.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/version.xml" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<example>
<title>Version Details Response: Atom</title>
<programlisting language="xml">
<xi:include href="samples/version-atom.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/version-atom.xml" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<example>
<title>Version Details Response: JSON</title>
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/version.json" parse="text"/></programlisting>
</example>
<para> The detailed version response contains pointers to
<para>The detailed version response contains pointers to
both a human-readable and a machine-processable
description of the API service. The
machine-processable description is written in the Web
@@ -1244,7 +1186,7 @@ Host: servers.api.openstack.org/v2/
<?hard-pagebreak?>
<section xml:id="Extensions-d1e1444">
<title>Extensions</title>
<para> The OpenStack Compute API is extensible. Extensions
<para>The OpenStack Compute API is extensible. Extensions
serve two purposes: They allow the introduction of new
features in the API without requiring a version change
and they allow the introduction of vendor specific
@@ -1284,18 +1226,16 @@ Host: servers.api.openstack.org/v2/
(<errorcode>400</errorcode>), badMethod
(<errorcode>405</errorcode>), overLimit
(<errorcode>413</errorcode>) </simpara>
<para> This operation does not require a request body.
Each extension is identified by two unique
identifiers, a <property>namespace</property> and an
<para>This operation does not require a request body. Each
extension is identified by two unique identifiers, a
<property>namespace</property> and an
<property>alias</property>. Additionally an
extension contains documentation links in various
formats. </para>
<?hard-pagebreak?>
<example>
<title>Extensions Response: XML</title>
<programlisting language="xml"><?db-font-size 90%?>
<xi:include href="samples/extensions.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/extensions.xml" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<example>
@@ -1303,9 +1243,9 @@ Host: servers.api.openstack.org/v2/
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/extensions.json" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<para> Extensions may also be queried individually by
their unique alias. This provides the simplest method
of checking if an extension is available as an
<para>Extensions may also be queried individually by their
unique alias. This provides the simplest method of
checking if an extension is available as an
unavailable extension will issue an itemNotFound
(<errorcode>404</errorcode>) response. </para>
<informaltable rules="all">
@@ -1343,15 +1283,13 @@ Host: servers.api.openstack.org/v2/
<?hard-pagebreak?>
<example>
<title>Extension Response: xml</title>
<programlisting language="xml"><?db-font-size 90%?>
<xi:include href="samples/extension.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/extension.xml" parse="text"/></programlisting>
</example>
<example>
<title>Extension Response: JSON</title>
<programlisting language="json"><?db-font-size 80%?><xi:include href="samples/extension.json" parse="text"/></programlisting>
</example>
<para> Extensions may define new data types, parameters,
<para>Extensions may define new data types, parameters,
actions, headers, states, and resources. In XML,
additional elements and attributes may be defined.
These elements must be defined in the extension's
@@ -1373,7 +1311,7 @@ Host: servers.api.openstack.org/v2/
followed by a colon. For example, an image may be in
the <code>RS-PIE:PrepareShare</code> state. </para>
<important>
<para> Applications should be prepared to ignore
<para>Applications should be prepared to ignore
response data that contains extension elements. An
extended state should always be treated as an
<code>UNKNOWN</code> state if the application
@@ -1383,9 +1321,7 @@ Host: servers.api.openstack.org/v2/
</important>
<example xml:id="ServersCBSX">
<title>Extended Server Response: XML</title>
<programlisting language="xml"><?db-font-size 90%?>
<xi:include href="samples/ext-servers.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/ext-servers.xml" parse="text"/></programlisting>
</example>
<example xml:id="ServersCBSJ">
<title>Extended Server Response: JSON</title>
@@ -1393,9 +1329,7 @@ Host: servers.api.openstack.org/v2/
</example>
<example xml:id="CBSAX">
<title>Extended Action: XML</title>
<programlisting language="xml"><?db-font-size 90%?>
<xi:include href="samples/ext-action.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/ext-action.xml" parse="text"/></programlisting>
</example>
<example xml:id="CBSAJ">
<title>Extended Action: JSON</title>
@@ -1407,11 +1341,11 @@ Host: servers.api.openstack.org/v2/
<title>Faults</title>
<section xml:id="Synchronous_Faults-d1e1729">
<title>Synchronous Faults</title>
<para> When an error occurs at request time, the
system will return an HTTP error response code
denoting the type of error. The system will also
return additional information about the fault in
the body of the response. </para>
<para>When an error occurs at request time, the system
will return an HTTP error response code denoting
the type of error. The system will also return
additional information about the fault in the body
of the response. </para>
<example>
<title>Fault Response: XML</title>
<programlisting language="xml"><xi:include href="samples/fault.xml" parse="text"/></programlisting>
@@ -1420,7 +1354,7 @@ Host: servers.api.openstack.org/v2/
<title>Fault Response: JSON</title>
<programlisting language="json"><xi:include href="samples/fault.json" parse="text"/></programlisting>
</example>
<para> The error code is returned in the body of the
<para>The error code is returned in the body of the
response for convenience. The message section
returns a human-readable message that is
appropriate for display to the end user. The
@@ -1429,7 +1363,7 @@ Host: servers.api.openstack.org/v2/
trace&mdash;to assist in tracking down an error.
The detail section may or may not be appropriate
for display to an end user. </para>
<para> The root element of the fault (e.g.
<para>The root element of the fault (e.g.
computeFault) may change depending on the type of
error. The following is a list of possible
elements along with their associated error codes. </para>
@@ -1525,14 +1459,14 @@ Host: servers.api.openstack.org/v2/
JSON</title>
<programlisting language="json"><xi:include href="samples/notfound.json" parse="text"/></programlisting>
</example>
<para> From an XML schema perspective, all API faults
<para>From an XML schema perspective, all API faults
are extensions of the base fault type
ComputeAPIFault. When working with a system that
binds XML to actual classes (such as JAXB), one
should be capable of using ComputeAPIFault as a
“catch-all” if there's no interest in
distinguishing between individual fault types. </para>
<para> The OverLimit fault is generated when a rate
<para>The OverLimit fault is generated when a rate
limit threshold is exceeded. For convenience, the
fault adds a <property>retryAfter</property>
attribute that contains the content of the
@@ -1549,7 +1483,7 @@ Host: servers.api.openstack.org/v2/
</section>
<section xml:id="Asynchronous_Faults-d1e2009">
<title>Asynchronous Faults</title>
<para> An error may occur in the background while a
<para>An error may occur in the background while a
server or image is being built or while a server
is executing an action. In these cases, the server
or image is placed in an <code>ERROR</code> state
@@ -2197,18 +2131,14 @@ Host: servers.api.openstack.org/v2/
<example>
<title>Creating a Server with a Access IP:
XML</title>
<programlisting language="xml">
<xi:include href="samples/server-post-req-pip.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/server-post-req-pip.xml" parse="text"/></programlisting>
</example>
<example>
<title>Creating a Server with a Access IP:
JSON</title>
<programlisting language="json">
<xi:include href="samples/server-post-req-pip.json" parse="text"/>
</programlisting>
<programlisting language="json"><xi:include href="samples/server-post-req-pip.json" parse="text"/></programlisting>
</example>
<para> Note that both IPv4 and IPv6 addresses may
<para>Note that both IPv4 and IPv6 addresses may
be used as access addresses and both addresses
may be assigned simultaneously as illustrated
below. Access addresses may be updated after a
@@ -2217,17 +2147,13 @@ Host: servers.api.openstack.org/v2/
<example>
<title>Creating a Server with Multiple Access
IPs: XML</title>
<programlisting language="xml">
<xi:include href="samples/server-post-req-pip2.xml" parse="text"/>
</programlisting>
<programlisting language="xml"><xi:include href="samples/server-post-req-pip2.xml" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<example>
<title>Creating a Server with Multiple Access
IPs: JSON</title>
<programlisting language="json">
<xi:include href="samples/server-post-req-pip2.json" parse="text"/>
</programlisting>
<programlisting language="json"><xi:include href="samples/server-post-req-pip2.json" parse="text"/></programlisting>
</example>
</section>
</section>
@@ -2396,7 +2322,7 @@ Host: servers.api.openstack.org/v2/
<programlisting language="json"><xi:include href="samples/server-put-resp.json" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>
<para> Access addresses may simultaneously be updated
<para>Access addresses may simultaneously be updated
as illustrated below. </para>
<example>
<title>Server Update Access Address Request:
@@ -3856,7 +3782,7 @@ Host: servers.api.openstack.org/v2/
<?hard-pagebreak?>
<section xml:id="MetadataSection">
<title>Metadata</title>
<para> The following operations allow access to metadata
<para>The following operations allow access to metadata
after a server or image has been created. </para>
<section xml:id="List_Metadata-d1e5089">
<title>List Metadata</title>

7
openstack-compute-api-2/src/samples/choices.xml
View File

@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
<choices xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<version id="v1.0" status="DEPRECATED">
@@ -11,7 +10,8 @@
</media-types>
<atom:link rel="self"
href="http://servers.api.openstack.org/v1.0/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/>
href="http://servers.api.openstack.org/v1.0/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
/>
</version>
<version id="v2" status="CURRENT">
@@ -23,6 +23,7 @@
</media-types>
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/>
href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
/>
</version>
</choices>

38
openstack-compute-api-2/src/samples/ext-servers.xml
View File

@@ -1,29 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<servers xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom">
<server id="52415800-8b69-11e0-9b19-734f6af67565"
tenant_id="1234" user_id="5678"
name="sample-server" status="BUILD"
<server id="52415800-8b69-11e0-9b19-734f6af67565" tenant_id="1234"
user_id="5678" name="sample-server" status="BUILD"
progress="60" hostId="e4d909c290d0fb1ca068ffaddf22cbd0"
updated="2010-10-10T12:00:00Z"
created="2010-08-10T12:00:00Z"
accessIPv4="67.23.10.132"
accessIPv6="::babe:67.23.10.132">
updated="2010-10-10T12:00:00Z" created="2010-08-10T12:00:00Z"
accessIPv4="67.23.10.132" accessIPv6="::babe:67.23.10.132">
<image id="52415800-8b69-11e0-9b19-734f6f006e54">
<atom:link
rel="self"
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/>
<atom:link
rel="bookmark"
href="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/>
<atom:link rel="bookmark"
href="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
/>
</image>
<flavor id="52415800-8b69-11e0-9b19-734f216543fd">
<atom:link
rel="self"
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/>
<atom:link
rel="bookmark"
href="http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/>
<atom:link rel="bookmark"
href="http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
/>
</flavor>
<metadata>
<meta key="Server Label">Web Head 1</meta>
@@ -41,18 +36,17 @@
<ip version="6" addr="::babe:10.176.42.16"/>
</network>
</addresses>
<atom:link
rel="self"
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/>
<atom:link
rel="bookmark"
<atom:link rel="bookmark"
href="http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/>
<volumes
xmlns="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0">
<volume name="OS"
href="https://cbs.api.rackspacecloud.com/12934/volumes/19"/>
<volume name="Work"
href="https://cbs.api.rackspacecloud.com/12934/volumes/23"/>
href="https://cbs.api.rackspacecloud.com/12934/volumes/23"
/>
</volumes>
</server>
</servers>

26
openstack-compute-api-2/src/samples/extension.xml
View File

@@ -1,24 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<extension
xmlns="http://docs.openstack.org/common/api/v1.0"
<extension xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom"
name="Public Image Extension"
namespace="http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0"
alias="RS-PIE"
updated="2011-01-22T13:25:27-06:00">
<description>
Adds the capability to share an image with other users.
</description>
<atom:link
rel="describedby"
type="application/pdf"
alias="RS-PIE" updated="2011-01-22T13:25:27-06:00">
<description> Adds the capability to share an image with other
users. </description>
<atom:link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"/>
<atom:link
rel="describedby"
type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"/>
<atom:link rel="describedby" type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"
/>
</extension>

42
openstack-compute-api-2/src/samples/extensions.xml
View File

@@ -1,43 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<extensions xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<extension
name="Public Image Extension"
<extension name="Public Image Extension"
namespace="http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0"
alias="RAX-PIE"
updated="2011-01-22T13:25:27-06:00">
<description>
Adds the capability to share an
image with other users.
</description>
<atom:link rel="describedby"
type="application/pdf"
alias="RAX-PIE" updated="2011-01-22T13:25:27-06:00">
<description> Adds the capability to share an image with other
users. </description>
<atom:link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"/>
<atom:link rel="describedby"
type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"/>
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"
/>
</extension>
<extension
name="Cloud Block Storage"
<extension name="Cloud Block Storage"
namespace="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0"
alias="RAX-CBS"
updated="2011-01-12T11:22:33-06:00"
>
<description>
Allows mounting cloud block
storage volumes.
</description>
<atom:link rel="describedby"
type="application/pdf"
alias="RAX-CBS" updated="2011-01-12T11:22:33-06:00">
<description> Allows mounting cloud block storage volumes.</description>
<atom:link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs-20111201.pdf"/>
<atom:link rel="describedby"
type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs.wadl"/>
href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs.wadl"
/>
</extension>
</extensions>

15
openstack-compute-api-2/src/samples/images-page1.xml
View File

@@ -1,13 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<images xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom">
<image id="52415800-8b69-11e0-9b19-734f6f006e54"
name="CentOS 5.2">
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/>
<image id="52415800-8b69-11e0-9b19-734f6f006e54" name="CentOS 5.2">
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
/>
</image>
<atom:link
rel="next"
href="http://servers.api.openstack.org/v2/1234/images?limit=1&amp;marker=52415800-8b69-11e0-9b19-734f6f006e54"/>
<atom:link rel="next"
href="http://servers.api.openstack.org/v2/1234/images?limit=1&amp;marker=52415800-8b69-11e0-9b19-734f6f006e54"
/>
</images>

10
openstack-compute-api-2/src/samples/server-post-req-short.json
View File

@@ -9,7 +9,15 @@
"personality": [
{
"path": "/etc/banner.txt",
"contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
"contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
}
]
}

10
openstack-compute-api-2/src/samples/server-post-req.json
View File

@@ -8,7 +8,15 @@
"name": "new-server-test",
"personality": [
{
"contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
"contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
"path": "/etc/banner.txt"
}
]

22
openstack-compute-api-2/src/samples/version.xml
View File

@@ -1,23 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<version xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom"
id="v2" status="CURRENT" updated="2011-01-21T11:33:21-06:00">
xmlns:atom="http://www.w3.org/2005/Atom" id="v2" status="CURRENT"
updated="2011-01-21T11:33:21-06:00">
<media-types>
<media-type base="application/xml"
type="application/vnd.openstack.compute.v2+xml"/>
<media-type base="application/json"
type="application/vnd.openstack.compute.v2+json"/>
</media-types>
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/"/>
<atom:link rel="describedby"
type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/v2/cs-devguide-20110125.pdf" />
<atom:link rel="describedby"
type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/v2/application.wadl" />
<atom:link rel="self" href="http://servers.api.openstack.org/v2/"/>
<atom:link rel="describedby" type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/v2/cs-devguide-20110125.pdf"/>
<atom:link rel="describedby" type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/v2/application.wadl"
/>
</version>

4
openstack-compute-api-2/src/samples/versions.xml
View File

@@ -1,18 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<versions xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<version id="v1.0" status="DEPRECATED"
updated="2009-10-09T11:30:00Z">
<atom:link rel="self"
href="http://servers.api.openstack.org/v1.0/"/>
</version>
<version id="v2" status="CURRENT"
updated="2010-12-12T18:30:02.25Z">
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/"/>
</version>
</versions>

80
openstack-compute-api-2/src/section_concepts.xml Normal file
View File

@@ -0,0 +1,80 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
]>
<section 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"
xml:id="concepts">
<?dbhtml stop-chunking?>
<title>Concepts</title>
<para>To use the OpenStack Compute API effectively, you should
understand several key concepts: </para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Server</emphasis></para>
<para>A virtual machine (VM) instance in the compute
system. Flavor and image are requisite elements when
creating a server. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Flavor</emphasis></para>
<para>An available hardware configuration for a server.
Each flavor has a unique combination of disk space,
memory capacity and priority for CPU time. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Image</emphasis></para>
<para>A collection of files used to create or rebuild a
server. Operators provide a number of pre-built OS
images by default. You may also create custom images
from cloud servers you have launched. These custom
images are useful for backup purposes or for producing
“gold” server images if you plan to deploy a
particular server configuration frequently. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Reboot</emphasis></para>
<para>Use this function to perform either a soft or hard
reboot of a server. With a soft reboot, the operating
system is signaled to restart, which allows for a
graceful shutdown of all processes. A hard reboot is
the equivalent of power cycling the server. The
virtualization platform should ensure that the reboot
action has completed successfully even in cases in
which the underlying domain/VM is paused or
halted/stopped. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Rebuild</emphasis></para>
<para>Use this function to remove all data on the server and
replaces it with the specified image. Server ID and IP
addresses remain the same. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Resize</emphasis></para>
<para>Use this function to convert an existing server to a
different flavor, in essence, scaling the server up or
down. The original server is saved for a period of
time to allow rollback if there is a problem. All
resizes should be tested and explicitly confirmed, at
which time the original server is removed. All resizes
are automatically confirmed after 24 hours if you do not
confirm or revert them. </para>
</listitem>
</itemizedlist>
</section>