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

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

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

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

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

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

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

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

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

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

@@ -9,7 +9,15 @@
"personality": [ "personality": [
{ {
"path": "/etc/banner.txt", "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", "name": "new-server-test",
"personality": [ "personality": [
{ {
"contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==", "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
"path": "/etc/banner.txt" "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"?> <?xml version="1.0" encoding="UTF-8"?>
<version xmlns="http://docs.openstack.org/common/api/v1.0" <version xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom" xmlns:atom="http://www.w3.org/2005/Atom" id="v2" status="CURRENT"
id="v2" status="CURRENT" updated="2011-01-21T11:33:21-06:00"> updated="2011-01-21T11:33:21-06:00">
<media-types> <media-types>
<media-type base="application/xml" <media-type base="application/xml"
type="application/vnd.openstack.compute.v2+xml"/> type="application/vnd.openstack.compute.v2+xml"/>
<media-type base="application/json" <media-type base="application/json"
type="application/vnd.openstack.compute.v2+json"/> type="application/vnd.openstack.compute.v2+json"/>
</media-types> </media-types>
<atom:link rel="self" href="http://servers.api.openstack.org/v2/"/>
<atom:link rel="self" <atom:link rel="describedby" type="application/pdf"
href="http://servers.api.openstack.org/v2/"/> href="http://docs.rackspacecloud.com/servers/api/v2/cs-devguide-20110125.pdf"/>
<atom:link rel="describedby" type="application/vnd.sun.wadl+xml"
<atom:link rel="describedby" href="http://docs.rackspacecloud.com/servers/api/v2/application.wadl"
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> </version>

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

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