3736 lines
178 KiB
XML
3736 lines
178 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE book [
|
||
<!-- Some useful entities borrowed from HTML -->
|
||
<!ENTITY ndash "–">
|
||
<!ENTITY mdash "—">
|
||
<!ENTITY hellip "…">
|
||
<!ENTITY plusmn "±">
|
||
|
||
<!-- 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>'>
|
||
|
||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||
<imageobject role="fo">
|
||
<imagedata fileref="figures/Check_mark_23x20_02.svg"
|
||
format="SVG" scale="60"/>
|
||
</imageobject>
|
||
<imageobject role="html">
|
||
<imagedata fileref="../figures/Check_mark_23x20_02.png"
|
||
format="PNG" />
|
||
</imageobject>
|
||
</inlinemediaobject>'>
|
||
|
||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||
<imageobject role="fo">
|
||
<imagedata fileref="figures/Arrow_east.svg"
|
||
format="SVG" scale="60"/>
|
||
</imageobject>
|
||
<imageobject role="html">
|
||
<imagedata fileref="../figures/Arrow_east.png"
|
||
format="PNG" />
|
||
</imageobject>
|
||
</inlinemediaobject>'>
|
||
]>
|
||
<book xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
xmlns:svg="http://www.w3.org/2000/svg"
|
||
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
||
xmlns:html="http://www.w3.org/1999/xhtml"
|
||
xmlns:db="http://docbook.org/ns/docbook"
|
||
version="5.0"
|
||
xml:id="os-cs-devguide">
|
||
<title>OpenStack Compute Developer Guide</title>
|
||
<titleabbrev>OpenStack Compute Dev Guide</titleabbrev>
|
||
<info>
|
||
<author>
|
||
<personname>
|
||
<firstname/>
|
||
<surname/>
|
||
</personname>
|
||
<affiliation>
|
||
<orgname>Rackspace Cloud</orgname>
|
||
</affiliation>
|
||
</author>
|
||
<copyright>
|
||
<year>2009</year>
|
||
<year>2010</year>
|
||
<year>2011</year>
|
||
<holder>Rackspace US, Inc.</holder>
|
||
</copyright>
|
||
<releaseinfo>API v1.1</releaseinfo>
|
||
<productname>OpenStack Compute</productname>
|
||
<pubdate>2011-11-08</pubdate>
|
||
<legalnotice role="apache2">
|
||
<annotation>
|
||
<remark>Copyright details are filled in by the template.</remark>
|
||
</annotation>
|
||
</legalnotice>
|
||
<abstract>
|
||
<para>This document is intended for software developers interested in developing
|
||
applications using the OpenStack Compute Application Programming Interface
|
||
(<abbrev>API</abbrev>). </para>
|
||
</abstract>
|
||
<revhistory>
|
||
<revision>
|
||
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
|
||
<date>2011-11-08</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>Removed DRAFT designation.</para>
|
||
</listitem>
|
||
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
|
||
<revision>
|
||
<date>2011-09-08</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem><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
|
||
password may be specified.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added tenant and user_id
|
||
attributes to server and
|
||
image.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added vcpus attribute to
|
||
flavors.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
We now use a flavorRef
|
||
in the resize action.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
<revision>
|
||
<date>2011-07-23</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
Added missing response
|
||
examples for server
|
||
update.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Ensure consistent HTTP
|
||
status codes for all
|
||
resources.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Clarifications on setting
|
||
and changing a server
|
||
password.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Minor updates to metadata
|
||
section for clarity.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Discuss alternate links.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Removed version number
|
||
from compute media types
|
||
— use a media type
|
||
parameter instead.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<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 server
|
||
action.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added minDisk and minRam
|
||
filters to flavor lists.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added minDisk and minRam
|
||
attributes to images.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Asynchronous faults may
|
||
now contain a timestamp.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Changes-since request
|
||
returns an empty list
|
||
rather than a 304.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added DELETED image status.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Fix content length in <xref
|
||
linkend="ImageCreateFullResponse"/>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Fixed bad request error code in <xref
|
||
linkend="Server_Passwords-d1e2510"/>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Compact image, server,
|
||
and flavor lists should
|
||
contain IDs, names, and
|
||
links (Any kind of link
|
||
may be included — not
|
||
just self links).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Changed metadata URI from
|
||
.../meta to .../metadata
|
||
for consistency.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
<revision>
|
||
<date>2011-06-29</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
Renamed Primary IP to
|
||
Access IP.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
<revision>
|
||
<date>2011-06-23</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
Many minor updates based
|
||
on community feedback.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Removed sections on
|
||
Content Compression,
|
||
Persistent Connections,
|
||
and Caching — these
|
||
are operator
|
||
specific. Added section
|
||
on HTTP.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
A Location header is
|
||
returned when creating
|
||
servers/images.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added filters to
|
||
collection of Image,
|
||
Servers, and Flavors.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added asynchronous faults.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<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>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added forbidden fault.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<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>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Previous links are no longer required.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Added the ability to create or update multiple metadata items simultaneously.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Minor cleanups to server and image state machine.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Update to JSON collection format.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Replace integer IDs with UUIDs.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Removed affinityID, this
|
||
will likely come in as an
|
||
extension.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
<revision>
|
||
<date>2011-04-25</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
Some minor cleanups in
|
||
preparation for OpenStack
|
||
Summit discussion.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
<revision>
|
||
<date>2011-03-11</date>
|
||
<revdescription><itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
Many minor updates based
|
||
on community feedback.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Updates to resource linking
|
||
and references.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Better description of
|
||
paginated collections.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Metadata supported in
|
||
servers and images.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Dropped support for
|
||
shared IP groups.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
IPs organized by network
|
||
id, vs simply having
|
||
public and private IPs.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Generalized affinity id.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist></revdescription>
|
||
</revision>
|
||
<revision>
|
||
<date>2011-02-09</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
Initial release.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
</revhistory>
|
||
|
||
|
||
</info>
|
||
<chapter xml:id="Overview-d1e71">
|
||
<title>Overview</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, and can
|
||
be provisioned in minutes. Interactions with Compute Servers can occur programmatically
|
||
via the OpenStack Compute API. </para>
|
||
<para>We welcome feedback, comments, and bug reports at <link
|
||
xlink:href="http://bugs.launchpad.net/nova">bugs.launchpad.net/nova</link>. </para>
|
||
<section xml:id="Intended_Audience-d1e85">
|
||
<title>Intended Audience</title>
|
||
<para>This Guide is intended to assist software developers who want to develop
|
||
applications using the OpenStack Compute API. To use the information provided here,
|
||
you should first have a general understanding of the OpenStack Compute service and
|
||
have access to an account from an OpenStack Compute provider. You should also be
|
||
familiar with: </para>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>RESTful web services</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>HTTP/1.1</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>JSON and/or XML data serialization formats</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Document_Change_History-d1e118">
|
||
<title>Document Change History</title>
|
||
<para>This version of the Developer Guide replaces and
|
||
obsoletes all previous versions. The most recent changes
|
||
are described in the table below:</para>
|
||
<!-- Table generated in output from revision element in the book element -->
|
||
<para><?rax revhistory?></para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Additional_Resources-d1e346">
|
||
<title>Additional Resources</title>
|
||
<para>You can download the most current version of this document from the OpenStack Docs
|
||
website at <link
|
||
xlink:href="http://docs.openstack.org">
|
||
http://docs.openstack.org</link>. </para>
|
||
<para> For more details about the Cloud Servers service that this API is based upon, please refer to <link
|
||
xlink:href="http://www.rackspacecloud.com/cloud_hosting_products/servers"
|
||
>http://www.rackspacecloud.com/cloud_hosting_products/servers</link>. Related
|
||
documents, including an <link
|
||
xlink:href="http://docs.rackspacecloud.com/servers/api/cs-bindguide-latest.pdf"
|
||
>API Language Binding Guide</link>, are available at the same site, as are links
|
||
to Rackspace's official support channels, including knowledge base articles, forums,
|
||
phone, chat, and email.</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.
|
||
</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">
|
||
<title>General API Information</title>
|
||
<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
|
||
the protocol such as caching, persistent connections, and
|
||
content compression among others. For example, providers
|
||
who employ a caching layer may respond with a 203 when a
|
||
request is served from the cache instead of a 200.
|
||
Additionally, providers may offer support for conditional
|
||
&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 communication
|
||
between the provider and client users.
|
||
</para>
|
||
<section xml:id="Authentication-d1e444">
|
||
<title>Authentication</title>
|
||
<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 Auth, Token). The
|
||
authentication scheme used is determined by the
|
||
provider of the OpenStack Compute system. Please contact
|
||
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>
|
||
</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>
|
||
<table rules="all">
|
||
<caption>JSON and XML Response Formats</caption>
|
||
<thead>
|
||
<tr>
|
||
<td>Format</td>
|
||
<td>Accept Header</td>
|
||
<td>Query Extension</td>
|
||
<td>Default</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>JSON</td>
|
||
<td>application/json</td>
|
||
<td>.json</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
<tr>
|
||
<td>XML</td>
|
||
<td>application/xml</td>
|
||
<td>.xml</td>
|
||
<td>No</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Request with Headers: JSON</title>
|
||
<literallayout class="monospaced">
|
||
POST /v1.1/214412/servers HTTP/1.1
|
||
Host: servers.api.openstack.org
|
||
Content-Type: application/json
|
||
Accept: application/xml
|
||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/server-post-req.json" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example xml:id="ImageCreateFullResponse">
|
||
<title>Response with Headers: XML</title>
|
||
<literallayout class="monospaced">
|
||
HTTP/1.1 200 OK
|
||
Date: Mon, 12 Nov 2007 15:55:01 GMT
|
||
Server: Apache
|
||
Content-Length: 1863
|
||
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 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
|
||
result is illustrated below – this time we utilize a
|
||
URI extension instead of an <code>Accept</code>
|
||
header.
|
||
</para>
|
||
<example>
|
||
<title>Request with Extension: JSON</title>
|
||
<literallayout class="monospaced">
|
||
POST /v1.1/214412/servers.xml HTTP/1.1
|
||
Host: servers.api.openstack.org
|
||
Content-Type: application/json
|
||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/server-post-req.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="LinksReferences">
|
||
<title>Links and References</title>
|
||
<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 remote
|
||
image. When providing an ID, it is assumed that the
|
||
resource exists in the current OpenStack deployment.
|
||
</para>
|
||
<example>
|
||
<title>ID Image Reference: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/server-post-req-short.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>ID Image Reference: JSON</title>
|
||
<programlisting language="javascript"><xi:include href="samples/server-post-req-short.json" parse="text"/></programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Full Image Reference: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/server-post-req.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Full Image Reference: JSON</title>
|
||
<programlisting language="javascript"><xi:include href="samples/server-post-req.json" parse="text"/></programlisting>
|
||
</example>
|
||
<para>
|
||
For convenience, resources contain links to
|
||
themselves. This allows a client to easily obtain a
|
||
resource URIs rather than to construct them. There
|
||
are three kinds of link relations associated with
|
||
resources. A <code>self</code> link contains a
|
||
versioned link to the resource. These links should be
|
||
used in cases where the link will be followed
|
||
immediately. A <code>bookmark</code> link provides a
|
||
permanent link to a resource that is appropriate for
|
||
long term storage. An <code>alternate</code> link can
|
||
contain an alternate representation of the resource.
|
||
For example, an OpenStack Compute image may have an
|
||
alternate representation in the OpenStack Image
|
||
service. Note that the type attribute here is used to
|
||
provide a hint as to the type of representation to
|
||
expect when following the link.
|
||
</para>
|
||
<example>
|
||
<title>Server with Self Links: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/server-simple.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server with Self Links: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include href="samples/server-simple.json" parse="text"/></programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Image with Alternate Link: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/image-simple.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server with Alternate Link: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include href="samples/image-simple.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Paginated_Collections-d1e664">
|
||
<title>Paginated Collections</title>
|
||
<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
|
||
parameters <parameter>limit</parameter> and
|
||
<parameter>marker</parameter> can be set in the URI
|
||
(e.g.?<parameter>limit</parameter>=100&<parameter>marker</parameter>=1234).
|
||
The <parameter>marker</parameter> parameter is the ID
|
||
of the last item in the previous list. Items are
|
||
sorted by create time in descending order. When a
|
||
create time is not available they are sorted by ID.
|
||
The <parameter>limit</parameter> parameter sets the
|
||
page size. Both parameters are optional. If the
|
||
client requests a <parameter>limit</parameter> beyond
|
||
that which is supported by the deployment an overLimit
|
||
(<errorcode>413</errorcode>) fault may be thrown. A
|
||
marker with an invalid ID will return an itemNotFound
|
||
(<errorcode>404</errorcode>) fault.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
Paginated collections never return itemNotFound
|
||
(<errorcode>404</errorcode>) faults when the
|
||
collection is empty — clients should expect
|
||
an empty collection.
|
||
</para>
|
||
</note>
|
||
<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/v1.1/1234/images?limit=1.
|
||
In these examples, the <parameter>limit</parameter>
|
||
parameter sets the page size to a single item.
|
||
Subsequent links will honor the initial page size.
|
||
Thus, a client may follow links to traverse a
|
||
paginated collection without having to input the
|
||
<parameter>marker</parameter> parameter.
|
||
</para>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Images Collection, First Page: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/images-page1.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Images Collection, First Page: JSON</title>
|
||
<programlisting language="javascript"><xi:include
|
||
href="samples/images-page1.json" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Images Collection, Second Page: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/images-page2.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Images Collection, Second Page: JSON</title>
|
||
<programlisting language="javascript"><xi:include
|
||
href="samples/images-page2.json" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Images Collection, Last Page: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/images-page3.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Images Collection, Last Page: JSON</title>
|
||
<programlisting language="javascript"><xi:include
|
||
href="samples/images-page3.json" parse="text"/></programlisting>
|
||
</example>
|
||
<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.
|
||
Properties about the collection itself, including
|
||
links, are contained in an array with the name of the
|
||
entity an underscore (_) and <code>links</code>. The
|
||
combination of the objects and arrays that start with
|
||
the name of the collection and an underscore
|
||
represent the collection in JSON. The approach allows
|
||
for extensibility of paginated collections by allowing
|
||
them to be associated with arbitrary properties. It
|
||
also allows collections to be embedded in other
|
||
objects as illustrated below. Here, a subset of
|
||
metadata items are presented within the image. Clients
|
||
must follow the "next" link to retrieve the full set
|
||
of metadata.
|
||
</para>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Paginated Metadata in an Image: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/image-meta-page1.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Paginated Metadata in an Image: JSON</title>
|
||
<programlisting language="javascript"><xi:include
|
||
href="samples/image-meta-page1.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="ChangesSince">
|
||
<title>Efficient Polling with the
|
||
<parameter>Changes-Since</parameter> Parameter</title>
|
||
<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
|
||
client may use the
|
||
<parameter>changes-since</parameter> parameter to
|
||
check for changes since a previous request. The
|
||
<parameter>changes-since</parameter> time is specified
|
||
as an <link
|
||
xlink:href="http://en.wikipedia.org/wiki/ISO_8601">ISO
|
||
8601</link> dateTime (2011-01-24T17:08Z). The form
|
||
for the timestamp is CCYY-MM-DDThh:mm:ss. An optional
|
||
time zone may be written in by appending the form
|
||
±hh:mm which describes the timezone as an
|
||
offset from UTC. When the timezone is not specified
|
||
(2011-01-24T17:08), the UTC timezone will be assumed.
|
||
If nothing has changed since the
|
||
<parameter>changes-since</parameter> time, an empty
|
||
list will be returned. If data has changed, only the
|
||
items changed since the specified time will be
|
||
returned in the response. For example, performing a
|
||
&GET; against
|
||
https://api.servers.openstack.org/v1.1/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>
|
||
In order 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
|
||
indicates that the resource has been
|
||
removed. Implementations are not required to keep
|
||
track of deleted resources indefinitely, so sending a
|
||
changes since time in the distant past may miss
|
||
deletions.
|
||
</para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Limits-d1e846">
|
||
<title>Limits</title>
|
||
<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
|
||
<firstterm>absolute limits</firstterm>. Rate limits
|
||
are thresholds that are reset after a certain amount
|
||
of time passes. Absolute limits are fixed. Limits are
|
||
configured by operators and may differ from one
|
||
deployment of the OpenStack Compute service to
|
||
another. Please contact your provider to determine the
|
||
limits that apply to your account or see <xref
|
||
linkend="ProgramaticLimits"/>. Your provider may be
|
||
able to adjust your account's limits if they are too
|
||
low.
|
||
</para>
|
||
<section xml:id="Rate_Limits-d1e862">
|
||
<title>Rate Limits</title>
|
||
<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
|
||
the rate limit takes effect after the root URI
|
||
path. For example, the regular expression
|
||
^/servers would match the bolded portion of the
|
||
following URI:
|
||
https://servers.api.openstack.org/v1.1/3542812<emphasis
|
||
role="bold">/servers</emphasis>.
|
||
</para>
|
||
<table rules="all">
|
||
<caption>Sample Rate Limits</caption>
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="2">RegEx</td>
|
||
<td colspan="1">Default</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">*</td>
|
||
<td colspan="2">.*</td>
|
||
<td colspan="1">10/min</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">*/servers</td>
|
||
<td colspan="2">^/servers</td>
|
||
<td colspan="1">50/day</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">*</td>
|
||
<td colspan="2">.*</td>
|
||
<td colspan="1">10/min</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">*changes-since*</td>
|
||
<td colspan="2">changes-since</td>
|
||
<td colspan="1">3/min</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&DELETE;</td>
|
||
<td colspan="2">*</td>
|
||
<td colspan="2">.*</td>
|
||
<td colspan="1">100/min</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<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
|
||
minute because the rate limits for any &POST; is
|
||
10/min.
|
||
</para>
|
||
<para>
|
||
In the event a request exceed the thresholds
|
||
established for your account, a
|
||
<errorcode>413</errorcode> HTTP response will be
|
||
returned with a <code>Retry-After</code> header to
|
||
notify the client when they can attempt to try
|
||
again.
|
||
</para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Absolute_Limits-d1e994">
|
||
<title>Absolute Limits</title>
|
||
<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
|
||
absolute value names. An absolute limit value is
|
||
always specified as an integer. The name of the
|
||
absolute limit determines the unit type of the
|
||
integer value. For example, the name
|
||
maxServerMeta implies that the value is in terms
|
||
of server metadata items.
|
||
</para>
|
||
<table rules="all">
|
||
<caption>Sample Absolute Limits</caption>
|
||
<thead>
|
||
<tr>
|
||
<td colspan="2">Name</td>
|
||
<td colspan="1">Value</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="2">maxTotalRAMSize</td>
|
||
<td colspan="1">51200</td>
|
||
<td colspan="3">Maximum total amount of
|
||
RAM (MB)</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">maxServerMeta</td>
|
||
<td colspan="1">5</td>
|
||
<td colspan="3">Maximum number of metadata items associated with a server</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">maxImageMeta</td>
|
||
<td colspan="1">5</td>
|
||
<td colspan="3">Maximum number of metadata items associated with an Image</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">maxPersonality</td>
|
||
<td colspan="1">5</td>
|
||
<td colspan="3">The maximum number of
|
||
file path/content pairs that can be
|
||
supplied on server build</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">maxPersonalitySize</td>
|
||
<td colspan="1">10240</td>
|
||
<td colspan="3">The maximum size, in
|
||
bytes, for each personality file</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="ProgramaticLimits">
|
||
<title>Determining Limits Programmatically</title>
|
||
<para>
|
||
Applications can programmatically determine
|
||
current account limits using the /limits URI as
|
||
follows:
|
||
</para>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/limits</td>
|
||
<td colspan="3">Returns the current limits for your account</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>)
|
||
</simpara>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Limit Response: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/limits.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Limit Response: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 75% ?><xi:include
|
||
href="samples/limits.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
<section xml:id="Versions-d1e1193">
|
||
<title>Versions</title>
|
||
<para>
|
||
The OpenStack Compute API uses both a URI and a MIME
|
||
type versioning scheme. In the URI scheme, the first
|
||
element of the path contains the target version
|
||
identifier (e.g. https://servers.api.openstack.org/
|
||
v1.0/…). The MIME type versioning scheme uses
|
||
HTTP content negotiation where the <code>Accept</code>
|
||
or <code>Content-Type</code> headers contains a MIME
|
||
type that identifies the version
|
||
(application/vnd.openstack.compute+xml;version=1.1). A
|
||
version MIME type is always linked to a base MIME type
|
||
(application/xml or application/json). If conflicting
|
||
versions are specified using both an HTTP header and a
|
||
URI, the URI takes precedence.
|
||
</para>
|
||
<example>
|
||
<title>Request with MIME type versioning</title>
|
||
<literallayout class="monospaced">
|
||
GET /214412/images HTTP/1.1
|
||
Host: servers.api.openstack.org
|
||
Accept: application/vnd.openstack.compute+xml;version=1.1
|
||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||
</literallayout>
|
||
</example>
|
||
<example>
|
||
<title>Request with URI versioning</title>
|
||
<literallayout class="monospaced">
|
||
GET /v1.1/214412/images HTTP/1.1
|
||
Host: servers.api.openstack.org
|
||
Accept: application/xml
|
||
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:
|
||
https://api.servers.openstack.org/224532/servers/123.
|
||
</para>
|
||
</note>
|
||
<?hard-pagebreak?>
|
||
<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>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Multiple Choices Response: JSON</title>
|
||
<programlisting language="javascript"><?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
|
||
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
|
||
functionality changes that would necessitate a break
|
||
in API-compatibility will require a new version, which
|
||
will result in URI and MIME type version being updated
|
||
accordingly. When new API versions are released, older
|
||
versions will be marked as
|
||
<code>DEPRECATED</code>. 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
|
||
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
|
||
authentication system. Note that an Atom
|
||
representation of the versions resources is supported
|
||
when issuing a request with the <code>Accept</code>
|
||
header containing application/atom+xml or by adding a
|
||
.atom to the request URI. This allows standard Atom
|
||
clients to track version changes.
|
||
</para>
|
||
<example>
|
||
<title>Versions List Request</title>
|
||
<literallayout class="monospaced">
|
||
GET HTTP/1.1
|
||
Host: servers.api.openstack.org
|
||
</literallayout>
|
||
</example>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>,
|
||
<returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
<errorcode>400</errorcode>,
|
||
<errorcode>413</errorcode>,
|
||
<errorcode>500</errorcode>,
|
||
<errorcode>503</errorcode>
|
||
</simpara>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Versions List Response: XML</title>
|
||
<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>
|
||
</example>
|
||
<example>
|
||
<title>Versions List Response: JSON</title>
|
||
<programlisting language="javascript"><?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
|
||
specific version by performing a &GET; on the base
|
||
version URL
|
||
(e.g. https://servers.api.openstack.org/v1.1/).
|
||
Version request URLs should always end with a trailing
|
||
slash (/). If the slash is omitted, the server may
|
||
respond with a <returnvalue>302</returnvalue>
|
||
redirection request. Format extensions may be placed
|
||
after the slash
|
||
(e.g. https://servers.api.openstack.org/v1.1/.xml). Note
|
||
that this is a special case that does not hold true
|
||
for other API requests. In general, requests such as
|
||
/servers.xml and /servers/.xml are handled
|
||
equivalently.
|
||
</para>
|
||
<example>
|
||
<title>Version Details Request</title>
|
||
<literallayout class="monospaced">
|
||
GET HTTP/1.1
|
||
Host: servers.api.openstack.org/v1.1/
|
||
</literallayout>
|
||
</example>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>)
|
||
</simpara>
|
||
<para>This operation does not require a request body</para>
|
||
<example>
|
||
<title>Version Details Response: XML</title>
|
||
<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>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Version Details Response: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include
|
||
href="samples/version.json" parse="text"/></programlisting>
|
||
</example>
|
||
<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
|
||
Application Description Language (WADL).
|
||
</para>
|
||
<note>
|
||
<para>If there is a discrepancy between the two specifications, the WADL is
|
||
authoritative as it contains the most accurate and up-to-date description of the
|
||
API service. </para>
|
||
</note>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Extensions-d1e1444">
|
||
<title>Extensions</title>
|
||
<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
|
||
niche functionality. Applications can programmatically
|
||
determine what extensions are available by performing
|
||
a &GET; on the /extensions URI. Note that this is a
|
||
versioned request — that is, an extension
|
||
available in one API version may not be available in
|
||
another.
|
||
</para>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/extensions</td>
|
||
<td colspan="3">List all available extensions</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<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
|
||
<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>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Extensions Response: JSON</title>
|
||
<programlisting language="javascript"><?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 unavailable
|
||
extension will issue an itemNotFound
|
||
(<errorcode>404</errorcode>) response.
|
||
</para>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/extensions/<parameter>alias</parameter></td>
|
||
<td colspan="3">Get details about a specific extension</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>)
|
||
</simpara>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Extension Response: xml</title>
|
||
<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="javascript"><?db-font-size 80%?><xi:include
|
||
href="samples/extension.json" parse="text"/></programlisting>
|
||
</example>
|
||
<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
|
||
namespace. In JSON, the alias must be used. The
|
||
volumes element in the <xref linkend="ServersCBSX"
|
||
xrefstyle="template: Examples %n"/> and <xref
|
||
linkend="ServersCBSJ" xrefstyle="select:
|
||
labelnumber"/> is defined in the <code>RS-CBS</code>
|
||
namespace. Actions work in exactly the same manner as
|
||
illustrated in <xref linkend="CBSAX"
|
||
xrefstyle="template: Examples %n"/> and <xref
|
||
linkend="CBSAJ" xrefstyle="select: labelnumber"/>.
|
||
Extended headers are always prefixed with
|
||
<code>X-</code> followed by the alias and a dash:
|
||
(<code>X-RS-CBS-HEADER1</code>). States and
|
||
parameters must be prefixed with the extension alias
|
||
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 response
|
||
data that contains extension elements. An
|
||
extended state should always be treated as an
|
||
<code>UNKNOWN</code> state if the application does
|
||
not support the extension. Applications should
|
||
also verify that an extension is available before
|
||
submitting an extended request.
|
||
</para>
|
||
</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>
|
||
</example>
|
||
<example xml:id="ServersCBSJ">
|
||
<title>Extended Server Response: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include
|
||
href="samples/ext-servers.json" parse="text"/></programlisting>
|
||
</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>
|
||
</example>
|
||
<example xml:id="CBSAJ">
|
||
<title>Extended Action: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include
|
||
href="samples/ext-action.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Faults-d1e1724">
|
||
<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>
|
||
<example>
|
||
<title>Fault Response: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/fault.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Fault Response: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/fault.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<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 details section is optional and may contain information—for example, a stack trace—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. computeFault)
|
||
may change depending on the type of error. The
|
||
following is a list of possible elements along with
|
||
their associated error codes.
|
||
</para>
|
||
<?hard-pagebreak?>
|
||
<table rules="all">
|
||
<caption>Fault Elements and Error Codes</caption>
|
||
<thead>
|
||
<tr>
|
||
<td>Fault Element</td>
|
||
<td>Associated Error Codes</td>
|
||
<td>Expected in All Requests?</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>computeFault</td>
|
||
<td>500, 400, other codes possible</td>
|
||
<td align="center">&CHECK;</td>
|
||
</tr>
|
||
<tr>
|
||
<td>serviceUnavailable</td>
|
||
<td>503</td>
|
||
<td align="center">&CHECK;</td>
|
||
</tr>
|
||
<tr>
|
||
<td>unauthorized</td>
|
||
<td>401</td>
|
||
<td align="center">&CHECK;</td>
|
||
</tr>
|
||
<tr>
|
||
<td>forbidden</td>
|
||
<td>403</td>
|
||
<td align="center">&CHECK;</td>
|
||
</tr>
|
||
<tr>
|
||
<td>badRequest</td>
|
||
<td>400</td>
|
||
<td align="center">&CHECK;</td>
|
||
</tr>
|
||
<tr>
|
||
<td>overLimit</td>
|
||
<td>413</td>
|
||
<td align="center">&CHECK;</td>
|
||
</tr>
|
||
<tr>
|
||
<td>badMediaType</td>
|
||
<td>415</td>
|
||
<td/>
|
||
</tr>
|
||
<tr>
|
||
<td>badMethod</td>
|
||
<td>405</td>
|
||
<td/>
|
||
</tr>
|
||
<tr>
|
||
<td>itemNotFound</td>
|
||
<td>404</td>
|
||
<td/>
|
||
</tr>
|
||
<tr>
|
||
<td>buildInProgress</td>
|
||
<td>409</td>
|
||
<td/>
|
||
</tr>
|
||
<tr>
|
||
<td>serverCapacityUnavailable</td>
|
||
<td>503</td>
|
||
<td/>
|
||
</tr>
|
||
<tr>
|
||
<td>backupOrResizeInProgress</td>
|
||
<td>409</td>
|
||
<td/>
|
||
</tr>
|
||
<tr>
|
||
<td>resizeNotAllowed</td>
|
||
<td>403</td>
|
||
<td/>
|
||
</tr>
|
||
<tr>
|
||
<td>notImplemented</td>
|
||
<td>501</td>
|
||
<td/>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<example>
|
||
<title>Fault Response, Item Not Found: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/notfound.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Fault Response, Item Not Found: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/notfound.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<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 limit
|
||
threshold is exceeded. For convenience, the fault
|
||
adds a <property>retryAt</property> attribute that
|
||
contains the content of the Retry-After header in XML
|
||
Schema 1.0 date/time format.
|
||
</para>
|
||
<example>
|
||
<title>Fault Response, Over Limit: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/overlimit.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Fault Response, Over Limit: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/overlimit.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Asynchronous_Faults-d1e2009">
|
||
<title>Asynchronous Faults</title>
|
||
<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 and the fault is embedded in the offending
|
||
server or image. Note that these asynchronous
|
||
faults follow the same format as the synchronous
|
||
ones. The fault contains an error code, a human
|
||
readable message, and optional details about the
|
||
error. Additionally, asynchronous faults may also
|
||
contain a created timestamp that specify when the
|
||
fault occured.
|
||
</para>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server In Error Sate: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/server-fault.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server In Error Sate: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/server-fault.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Image In Error Sate: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/image-fault.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Image In Error Sate: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/image-fault.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
</chapter>
|
||
<chapter xml:id="API_Operations-d1e2068">
|
||
<title>API Operations</title>
|
||
<section xml:id="Servers-d1e2073">
|
||
<title>Servers</title>
|
||
<section xml:id="List_Servers-d1e2078">
|
||
<title>List Servers</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/servers?<parameter>image</parameter>=<literal>imageRef</literal>&
|
||
<parameter>flavor</parameter>=<literal>flavorRef</literal>&
|
||
<parameter>name</parameter>=<literal>serverName</literal>&
|
||
<parameter>status</parameter>=<literal>serverStatus</literal>&
|
||
<parameter>marker</parameter>=<literal>markerID</literal>&<parameter>limit</parameter>=<literal>int</literal>&
|
||
<parameter>changes-since</parameter>=<literal>dateTime</literal>
|
||
</td>
|
||
<td colspan="3">List all servers (IDs, names, links)</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/servers/detail?<parameter>image</parameter>=<literal>imageRef</literal>&
|
||
<parameter>flavor</parameter>=<literal>flavorRef</literal>&
|
||
<parameter>name</parameter>=<literal>serverName</literal>&
|
||
<parameter>status</parameter>=<literal>serverStatus</literal>&
|
||
<parameter>marker</parameter>=<literal>markerID</literal>&<parameter>limit</parameter>=<literal>int</literal>&
|
||
<parameter>changes-since</parameter>=<literal>dateTime</literal>
|
||
</td>
|
||
<td colspan="3">List all servers (all details)</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>)
|
||
</simpara>
|
||
<annotation annotates="id35836359">
|
||
<info>
|
||
<title>Office Annotation</title>
|
||
<author>
|
||
<personname>
|
||
<othername role="full">Jorge Williams</othername>
|
||
</personname>
|
||
</author>
|
||
<date>2009-06-26T14:30:46</date>
|
||
</info>
|
||
<para>
|
||
Well need to revisit. List all status even
|
||
the ones that don't enter into our state
|
||
transitions along with descriptions of each.
|
||
</para>
|
||
</annotation>
|
||
<para xml:id="id35836359">
|
||
This operation provides a list of servers
|
||
associated with your account. Servers that have
|
||
been deleted are not included in this list.
|
||
Servers contain a status attribute that can be
|
||
used as an indication of the current server state.
|
||
Servers with an <code>ACTIVE</code> status are
|
||
available for use. Other possible values for the
|
||
status attribute include: <code>BUILD</code>,
|
||
<code>REBUILD</code>, <code>SUSPENDED</code>,
|
||
<code>RESIZE</code>, <code>VERIFY_RESIZE</code>,
|
||
<code>REVERT_RESIZE</code>,
|
||
<code>PASSWORD</code>, <code>REBOOT</code>,
|
||
<code>HARD_REBOOT</code>, <code>DELETED</code>,
|
||
<code>UNKNOWN</code>, and <code>ERROR</code>.
|
||
</para>
|
||
<para>
|
||
The list of servers may be filtered by image,
|
||
flavor, name, and status via the respective query
|
||
parameters. Image and flavor references may be IDs
|
||
or full URLs. When retrieving a list of servers
|
||
via the changes-since parameter, the list will
|
||
contain servers that have been deleted since the
|
||
changes-since time (see <xref
|
||
linkend="ChangesSince"/>).
|
||
</para>
|
||
<para>
|
||
The compute provisioning algorithm has an
|
||
anti-affinity property that attempts to spread out
|
||
customer VMs across hosts. Under certain
|
||
situations, VMs from the same customer may be
|
||
placed on the same host.
|
||
<property>hostId</property> represents the host
|
||
your server runs on and can be used to determine
|
||
this scenario if it's relevant to your
|
||
application.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
<property>HostId</property> is unique
|
||
<emphasis>per account</emphasis> and is not
|
||
globally unique.
|
||
</para>
|
||
</note>
|
||
<para>This operation does not require a request body.</para>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Servers List Response: XML (detail)</title>
|
||
<programlisting language="xml"><?db-font-size 80%?>
|
||
<xi:include href="samples/servers.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Servers List Response: JSON (detail)</title>
|
||
<programlisting language="javascript"><?db-font-size 80%?>
|
||
<xi:include href="samples/servers.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="CreateServers">
|
||
<title>Create Server</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers</td>
|
||
<td colspan="3">Create a new server</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>202</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
serverCapacityUnavailable (<errorcode>503</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>BUILD</code> &ARROW; <code>ACTIVE</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" />
|
||
<td colspan="3">
|
||
<code>BUILD</code> &ARROW; <code>ERROR</code> (on error)
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>
|
||
This operation asynchronously provisions a new
|
||
server. The progress of this operation depends on
|
||
several factors including location of the
|
||
requested image, network i/o, host load, and the
|
||
selected flavor. The progress of the request can
|
||
be checked by performing a &GET; on
|
||
/servers/<parameter>id</parameter>, which will
|
||
return a progress attribute (0-100% completion).
|
||
The full URL to the newly created server is
|
||
returned via the <code>Location</code> header and
|
||
is available as a <code>self</code> and
|
||
<code>bookmark</code> link in the server
|
||
representation (See <xref
|
||
linkend="LinksReferences"/>). Note that when
|
||
creating a server only the server ID, its links,
|
||
and the admin password are guaranteed to be
|
||
returned in the request. Additional
|
||
attributes may be retrieved by performing
|
||
subsequent &GET;s on the server.
|
||
</para>
|
||
<example>
|
||
<title>Server Create Request: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/server-post-req.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Create Request: JSON</title>
|
||
<programlisting language="javascript"><xi:include href="samples/server-post-req.json" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Create Response: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/server-post-resp.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Create Response: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include href="samples/server-post-resp.json" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Server_Passwords-d1e2510">
|
||
<title>Server Passwords</title>
|
||
<para>
|
||
A password may be specified when creating the
|
||
server via the optional
|
||
<property>adminPass</property> attribute. The
|
||
specified password must meet the complexity
|
||
requirements set by your OpenStack Compute
|
||
provider. The server may enter an
|
||
<code>ERROR</code> state if the complexity
|
||
requirements are not met. In this case, an
|
||
client may issue a change password action to
|
||
reset the server password (see <xref
|
||
linkend="Change_Password-d1e3234"/>).
|
||
</para>
|
||
<para>
|
||
If a password is not specified, a randomly
|
||
generated password will be assigned and
|
||
returned in the response object. This password
|
||
is guaranteed to meet the security requirements
|
||
set by the compute provider. For security
|
||
reasons, the password will not be returned in
|
||
subsequent &GET; calls.
|
||
</para>
|
||
</section>
|
||
<section xml:id="Server_Metadata-d1e2529">
|
||
<title>Server Metadata</title>
|
||
<para>
|
||
Custom server metadata can also be supplied at
|
||
launch time. See <xref
|
||
linkend="MetadataSection"/> for details on
|
||
working with metadata. The maximum size of
|
||
the metadata key and value is 255 bytes each.
|
||
The maximum number of key-value pairs that can
|
||
be supplied per server is determined by the
|
||
compute provider and may be queried via the
|
||
maxServerMeta absolute limit.
|
||
</para>
|
||
</section>
|
||
<section xml:id="Server_Personality-d1e2543">
|
||
<title>Server Personality</title>
|
||
<para>
|
||
You may further customize a server by
|
||
injecting data into the file system of the
|
||
server itself. This is useful, for example,
|
||
for inserting ssh keys, setting configuration
|
||
files, or storing data that you want to
|
||
retrieve from within the instance itself. It
|
||
is intended to provide a minimal amount of
|
||
launch-time personalization. If significant
|
||
customization is required, a custom image
|
||
should be created. The max size of the file
|
||
path data is 255 bytes. The max size of the
|
||
file contents is determined by the compute
|
||
provider and may vary based on the image that
|
||
is used to create the server. The absolute
|
||
limit maxPersonalitySize is a byte limit that
|
||
is guaranteed to apply to all images in the
|
||
deployment. Providers may set additional
|
||
per-image personality limits. Note that file
|
||
contents should be encoded as a Base64 string
|
||
and these limits refer to the number of
|
||
bytes in the decoded data not the number of
|
||
characters in the encoded data. The maximum
|
||
number of file path/content pairs that can be
|
||
supplied is also determined by the compute
|
||
provider and is denoted by the maxPersonality
|
||
absolute limit.
|
||
</para>
|
||
<para>
|
||
Any existing files that match the specified
|
||
file will be renamed to include the extension
|
||
bak followed by a time stamp. For example,
|
||
the file /etc/passwd will be backed up as
|
||
/etc/passwd.bak.1246036261.5785. Personality
|
||
files will be accessible only to system
|
||
administrators. For example, in Linux files
|
||
will have root and the root group as owner and
|
||
group owner, respectively and will allow user
|
||
and group read access only (
|
||
<code>-r--r-----</code> ).
|
||
</para>
|
||
</section>
|
||
<section xml:id="Server_Primary_Addresses-d1e2558">
|
||
<title>Server Access Addresses</title>
|
||
<para>
|
||
In a hybrid environment, the IP address of a
|
||
server may not be controlled by the underling
|
||
implementation. Instead, the access IP address
|
||
may be part of the dedicated hardware; for
|
||
example, a router/NAT device. In this case,
|
||
the addresses provided by the implementation
|
||
cannot actually be used to access the server
|
||
(from outside the local LAN). Here, a separate
|
||
<firstterm>access address</firstterm> may be
|
||
assigned at creation time to provide access to
|
||
the server. This address may not be directly
|
||
bound to a network interface on the server and
|
||
may not necessarily appear when a server's
|
||
addresses are queried (see <xref
|
||
linkend="ServerAddresses"/>). Nonetheless,
|
||
clients which need to access the server
|
||
directly are encouraged to do so via an access
|
||
address. In the example below, an IPv4
|
||
address is assigned at creation time.
|
||
</para>
|
||
<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>
|
||
</example>
|
||
<example>
|
||
<title>Creating a Server with a Access IP: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/server-post-req-pip.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<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 server has been created. See <xref
|
||
linkend="ServerUpdate"/> for more details.
|
||
</para>
|
||
<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>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Creating a Server with Multiple Access IPs: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/server-post-req-pip2.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Get_Server_Details-d1e2623">
|
||
<title>Get Server Details</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter></td>
|
||
<td colspan="3">List details of the specified server</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation returns the details of a specific
|
||
server by its ID.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Details Response: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/server.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Details Response: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include href="samples/server.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="ServerUpdate">
|
||
<title>Update Server</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter></td>
|
||
<td colspan="3">Update the specified
|
||
server's editable attributes</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>ACTIVE</code>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para> This operation updates the editable attributes of a server: the name of the
|
||
server and the IPv4 and IPv6 access addresses. Note that while the server name
|
||
is editable, the operation does not change the server host name. Note also that
|
||
server names are not guaranteed to be unique. </para>
|
||
<example>
|
||
<title>Server Update Name Request: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/server-put-req.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Server Update Name Request: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/server-put-req.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Update Name Response: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/server-put-resp.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Update Name Response: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/server-put-resp.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<para>
|
||
Access addresses may simultaneously be updated as
|
||
illustrated below.
|
||
</para>
|
||
<example>
|
||
<title>Server Update Access Address Request: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/server-put-req-ad.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Server Update Access Address Request: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/server-put-req-ad.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Update Access Address Response: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/server-put-resp-ad.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Server Update Access Address Response: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/server-put-resp-ad.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Delete_Server-d1e2883">
|
||
<title>Delete Server</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&DELETE;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter></td>
|
||
<td colspan="3">Terminate the specified server</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>DELETED</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" />
|
||
<td colspan="3">
|
||
<code>ERROR</code> &ARROW;
|
||
<code>DELETED</code>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>This operation deletes a cloud server instance from the system. It does not require a request or a response body.</para>
|
||
</section>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="ServerAddresses">
|
||
<title>Server Addresses</title>
|
||
<section xml:id="List_Addresses-d1e3014">
|
||
<title>List Addresses</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/ips</td>
|
||
<td colspan="3">List all server addresses</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<para>This operation does not require a request body.</para>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Addresses List Response: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/addresses.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Addresses List Response: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/addresses.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="List_Addresses_by_Network-d1e3118">
|
||
<title>List Addresses by Network</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/ips/<parameter>networkID</parameter></td>
|
||
<td colspan="3">List addresses by Network ID</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>List Addresses by Network: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/public.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>List Addresses by Network: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/public.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Server_Actions-d1e3229">
|
||
<title>Server Actions</title>
|
||
<section xml:id="Change_Password-d1e3234">
|
||
<title>Change Password</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/action</td>
|
||
<td colspan="3">Change a server's password</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>202</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>PASSWORD</code> &ARROW;
|
||
<code>ACTIVE</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1"/>
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>PASSWORD</code> &ARROW;
|
||
<code>ERROR</code> (on error)
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1"/>
|
||
<td colspan="3">
|
||
<code>ERROR</code> &ARROW;
|
||
<code>PASSWORD</code> &ARROW;
|
||
<code>ACTIVE</code> (password reset
|
||
after error)
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>
|
||
This operation changes the server's administrator
|
||
password. The specified password must meet the
|
||
complexity requirements set by your OpenStack
|
||
Compute provider. The server may enter an
|
||
<code>ERROR</code> state if the complexity
|
||
requirements are not met. In this case, a client
|
||
may reissue the change password action.
|
||
</para>
|
||
<example>
|
||
<title>Server Update Request: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/changepassword.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Server Update Request: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/changepassword.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<para>This operation does not contain a response body.</para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Reboot_Server-d1e3371">
|
||
<title>Reboot Server</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/action</td>
|
||
<td colspan="3">Reboot the specified server</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>202</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>REBOOT</code> &ARROW;
|
||
<code>ACTIVE</code> (<property>soft reboot</property>)
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" />
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>HARD_REBOOT</code> &ARROW;
|
||
<code>ACTIVE</code> (<property>hard reboot</property>)
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>
|
||
The reboot function allows for either a soft or
|
||
hard reboot of a server. With a soft reboot
|
||
(<code>SOFT</code>), the operating system is signaled to
|
||
restart, which allows for a graceful shutdown of
|
||
all processes. A hard reboot (<code>HARD</code>) is the
|
||
equivalent of power cycling the server.
|
||
</para>
|
||
<example>
|
||
<title>Action Reboot: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/reboot.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Action Reboot: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/reboot.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<para>This operation does not return a response body.</para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Rebuild_Server-d1e3538">
|
||
<title>Rebuild Server</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/action</td>
|
||
<td colspan="3">Rebuild the specified server</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>202</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
serverCapacityUnavailable (<errorcode>503</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>REBUILD</code> &ARROW;
|
||
<code>ACTIVE</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" />
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>REBUILD</code> &ARROW;
|
||
<code>ERROR</code> (on error)
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>
|
||
The rebuild function removes all data on the
|
||
server and replaces it with the specified
|
||
image. The <property>serverRef</property> and all
|
||
IP addresses will remain the same. If
|
||
<property>name</property>,
|
||
<property>metadata</property>,
|
||
<property>accessIPv4</property>, or
|
||
<property>accessIPv6</property> are specified, they
|
||
will replace existing values, otherwise they will
|
||
not change. A rebuild operation always removes
|
||
data injected into the file system via server
|
||
<property>personality</property>. You may
|
||
reinsert data into the filesystem during the
|
||
rebuild. The full URL to the rebuild server
|
||
is returned via the <code>Location</code> header.
|
||
</para>
|
||
<example>
|
||
<title>Action Rebuild Request: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/rebuild_all.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Action Rebuild Request: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/rebuild_all.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Action Rebuild Response: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/rebuild-resp.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Action Rebuild Response: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include href="samples/rebuild-resp.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Resize_Server-d1e3707">
|
||
<title>Resize Server</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/action</td>
|
||
<td colspan="3">Resize the specified server</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>202</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
resizeNotAllowed (<errorcode>403</errorcode>),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
serverCapacityUnavailable (<errorcode>503</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>RESIZE</code> &ARROW;
|
||
<code>VERIFY_RESIZE</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" />
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW;
|
||
<code>RESIZE</code> &ARROW;
|
||
<code>ACTIVE</code> (on error)
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<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
|
||
explicitly confirmed or reverted.
|
||
</para>
|
||
<example>
|
||
<title>Action Resize: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/resize.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Action Resize: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/resize.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<para>This operation does not return a response body.</para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Confirm_Resized_Server-d1e3868">
|
||
<title>Confirm Resized Server</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/action</td>
|
||
<td colspan="3">Confirm a pending resize action</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
resizeNotAllowed (<errorcode>403</errorcode>),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
serverCapacityUnavailable (<errorcode>503</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>VERIFY_RESIZE</code> &ARROW;
|
||
<code>ACTIVE</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" />
|
||
<td colspan="3">
|
||
<code>VERIFY_RESIZE</code> &ARROW;
|
||
<code>ERROR</code> (on error)
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>
|
||
During a resize operation, the original server is
|
||
saved for a period of time to allow roll back if
|
||
there is a problem. Once the newly resized server
|
||
is tested and has been confirmed to be functioning
|
||
properly, use this operation to confirm the
|
||
resize. After confirmation, the original server
|
||
is removed and cannot be rolled back to. All
|
||
resizes are automatically confirmed after 24 hours
|
||
if they are not explicitly confirmed or reverted.
|
||
</para>
|
||
<example>
|
||
<title>Action Confirm Resize: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/confirmresize.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Action Confirm Resize: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/confirmresize.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<para>This operation does not return a response body.</para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Revert_Resized_Server-d1e4024">
|
||
<title>Revert Resized Server</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/action</td>
|
||
<td colspan="3">Cancel and revert a pending resize action</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>202</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
resizeNotAllowed (<errorcode>403</errorcode>),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
serverCapacityUnavailable (<errorcode>503</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>VERIFY_RESIZE</code> &ARROW;
|
||
<code>REVERT_RESIZE</code> &ARROW;
|
||
<code>ACTIVE</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" />
|
||
<td colspan="3">
|
||
<code>VERIFY_RESIZE</code> &ARROW;
|
||
<code>REVERT_RESIZE</code> &ARROW;
|
||
<code>ERROR</code> (on error)
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>
|
||
During a resize operation, the original server is
|
||
saved for a period of time to allow for roll back
|
||
if there is a problem. If you determine there is a
|
||
problem with a newly resized server, use this
|
||
operation to revert the resize and roll back to
|
||
the original server. All resizes are automatically
|
||
confirmed after 24 hours if they have not already
|
||
been confirmed explicitly or reverted.
|
||
</para>
|
||
<example>
|
||
<title>Action Revert Resize: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/revertresize.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Action Revert Resize: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/revertresize.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<para>This operation does not return a response body.</para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Create_Image-d1e4655">
|
||
<title>Create Image</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/action</td>
|
||
<td colspan="3">Creates a new image.</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>202</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
backupOrResizeInProgress (<errorcode>409</errorcode>),
|
||
resizeNotAllowed (<errorcode>403</errorcode>),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
serverCapacityUnavailable (<errorcode>503</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Image Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>SAVING</code> &ARROW; <code>ACTIVE</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" />
|
||
<td colspan="3">
|
||
<code>SAVING</code> &ARROW; <code>ERROR</code> (on error)
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>
|
||
This action creates a new image for the given
|
||
server. Once complete, a new image will be
|
||
available that can be used to rebuild or create
|
||
servers. The full URL to the newly created image
|
||
is returned via the <code>Location</code> header,
|
||
additional attributes for the image including
|
||
creation status may be retrieved by performing a
|
||
subsequent &GET; on that URL. See <xref
|
||
linkend="Get_Image_Details-d1e4848"/> for details.
|
||
</para>
|
||
<para>
|
||
Custom image metadata can also be supplied when
|
||
creating an image. See <xref
|
||
linkend="MetadataSection"/> for details on working
|
||
with metadata. The maximum size of the metadata
|
||
key and value is 255 bytes each. The maximum
|
||
number of key-value pairs that can be supplied per
|
||
image is determined by the compute provider and
|
||
may be queried via the maxImageMeta absolute
|
||
limit.
|
||
</para>
|
||
<para>This operation does not return a response body.</para>
|
||
<note>
|
||
<para>
|
||
At present, image creation is an asynchronous
|
||
operation, so coordinating the creation with
|
||
data quiescence, etc. is currently not
|
||
possible.
|
||
</para>
|
||
</note>
|
||
<example>
|
||
<title>Action Create Image: XML</title>
|
||
<programlisting language="xml"><xi:include href="samples/createimage.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Action Create Image: JSON</title>
|
||
<programlisting language="javascript"><xi:include href="samples/createimage.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Flavors-d1e4180">
|
||
<title>Flavors</title>
|
||
<para>
|
||
A flavor is an available hardware configuration for a
|
||
server. Each flavor has a unique combination of disk
|
||
space and memory capacity.
|
||
</para>
|
||
<section xml:id="List_Flavors-d1e4188">
|
||
<title>List Flavors</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td
|
||
colspan="2">/flavors?<parameter>minDisk</parameter>=<literal>minDiskInGB</literal>&
|
||
<parameter>minRam</parameter>=<literal>minRamInMB</literal>&
|
||
<parameter>marker</parameter>=<literal>markerID</literal>&<parameter>limit</parameter>=<literal>int</literal>
|
||
</td>
|
||
<td colspan="3">List available flavors (IDs, names, links)</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td
|
||
colspan="2">/flavors/detail?<parameter>minDisk</parameter>=<literal>minDiskInGB</literal>&
|
||
<parameter>minRam</parameter>=<literal>minRamInMB</literal>&
|
||
<parameter>marker</parameter>=<literal>markerID</literal>&<parameter>limit</parameter>=<literal>int</literal></td>
|
||
<td colspan="3">List available flavors (all details)</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation will list all available flavors.
|
||
The <parameter>minDisk</parameter> parameter can
|
||
narrow the list of flavors to those which contain
|
||
at least the specified number of gigabytes of disk
|
||
storage. The <parameter>minRam</parameter>
|
||
parameter narrows the list of flavors to those
|
||
that contain at least the specified amount of RAM
|
||
in megabytes.
|
||
</para>
|
||
<para>
|
||
This operation does not require a request body.
|
||
</para>
|
||
<example>
|
||
<title>Flavors List Response: XML (detail) </title>
|
||
<programlisting language="xml"><xi:include href="samples/flavors.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Flavors List Response: JSON (detail)</title>
|
||
<programlisting language="javascript"><?db-font-size 90% ?><xi:include href="samples/flavors.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Get_Flavor_Details-d1e4317">
|
||
<title>Get Flavor Details</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/flavors/<parameter>id</parameter></td>
|
||
<td colspan="3">List details of the specified flavor</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>)
|
||
</simpara>
|
||
<para>This operation returns details of the specified flavor.</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Flavor Details Response: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/flavor.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Flavor Details Response: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/flavor.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Images-d1e4427">
|
||
<title>Images</title>
|
||
<para>
|
||
An image is a collection of files you use to create or
|
||
rebuild a server. Operators provide pre-built OS
|
||
images by default. You may also create custom images.
|
||
</para>
|
||
<section xml:id="List_Images-d1e4435">
|
||
<title>List Images</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/images?<parameter>server</parameter>=<literal>serverRef</literal>&
|
||
<parameter>name</parameter>=<literal>imageName</literal>&
|
||
<parameter>status</parameter>=<literal>imageStatus</literal>&
|
||
<parameter>changes-since</parameter>=<literal>dateTime</literal>&
|
||
<parameter>marker</parameter>=<literal>markerID</literal>&<parameter>limit</parameter>=<literal>int</literal>&
|
||
<parameter>type</parameter>=(<constant>BASE</constant>|<constant>SERVER</constant>)
|
||
</td>
|
||
<td colspan="3">List available images (IDs, names, links)</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/images/detail?<parameter>server</parameter>=<literal>serverRef</literal>&
|
||
<parameter>name</parameter>=<literal>imageName</literal>&
|
||
<parameter>status</parameter>=<literal>imageStatus</literal>&
|
||
<parameter>changes-since</parameter>=<literal>dateTime</literal>&
|
||
<parameter>marker</parameter>=<literal>markerID</literal>&<parameter>limit</parameter>=<literal>int</literal>&
|
||
<parameter>type</parameter>=(<constant>BASE</constant>|<constant>SERVER</constant>)
|
||
</td>
|
||
<td colspan="3">List available images (all details)</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation will list all images visible by the
|
||
account.
|
||
</para>
|
||
<para>
|
||
In-flight images will have the status attribute
|
||
set to <code>SAVING</code> and the conditional
|
||
progress element (0-100% completion) will also be
|
||
returned. Other possible values for the status
|
||
attribute include: <code>UNKNOWN</code>,
|
||
<code>ACTIVE</code>, <code>SAVING</code>,
|
||
<code>ERROR</code>, and
|
||
<code>DELETED</code>. Images with an
|
||
<code>ACTIVE</code> status are available for
|
||
install. The optional minDisk and minRam
|
||
attributes set the minimum disk and RAM
|
||
requirements needed to create a server with the
|
||
image.
|
||
</para>
|
||
<para>
|
||
The list of images may be filtered by server,
|
||
name, and status via the respective query
|
||
parameters. A server reference may be specified by
|
||
ID or with a full URL. The
|
||
<parameter>type</parameter> parameter will select
|
||
only base images (<constant>BASE</constant>) or
|
||
server backups (<constant>SERVER</constant>).
|
||
When using the changes-since parameter
|
||
the list of images will contain images that have
|
||
changed since the changes-since time. See
|
||
<xref linkend="ChangesSince"/> for details.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Images List Response: XML (detail)</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/images.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Images List Response: JSON (detail)</title>
|
||
<programlisting language="javascript"><?db-font-size 80%?><xi:include href="samples/images.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Get_Image_Details-d1e4848">
|
||
<title>Get Image Details</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/images/<parameter>id</parameter></td>
|
||
<td colspan="3">List details of the specified image</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>)
|
||
</simpara>
|
||
<para>This operation returns details of the specified image.</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Image Details Response: XML</title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/image.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Image Details Response: JSON</title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/image.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Delete_Image-d1e4957">
|
||
<title>Delete Image</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&DELETE;</td>
|
||
<td colspan="2">/images/<parameter>id</parameter></td>
|
||
<td colspan="3">Deletes the specified image.</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>)
|
||
</simpara>
|
||
<informaltable frame="void">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">Status Transition:</td>
|
||
<td colspan="3">
|
||
<code>ACTIVE</code> &ARROW; <code>DELETED</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1"/>
|
||
<td colspan="3">
|
||
<code>ERROR</code> &ARROW; <code>DELETED</code>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<para>This operation deletes an image from the system.</para>
|
||
<para>
|
||
Images are immediately removed. Currently, there
|
||
are no state transitions to track the delete
|
||
operation.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<para>This operation does not contain a response body.</para>
|
||
</section>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="MetadataSection">
|
||
<title>Metadata</title>
|
||
<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>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/metadata</td>
|
||
<td colspan="3">List metadata associated
|
||
with a server</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/images/<parameter>id</parameter>/metadata</td>
|
||
<td colspan="3">List metadata associated
|
||
with an image</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
Lists all metadata. This operation does not
|
||
require a request body.
|
||
</para>
|
||
<example>
|
||
<title>Metadata List Response: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/metadata.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Metadata List Response: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/metadata.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Create_or_Replace_Metadata-d1e5358">
|
||
<title>Set Metadata</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/metadata</td>
|
||
<td colspan="3">Set metadata</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/images/<parameter>id</parameter>/metadata</td>
|
||
<td colspan="3">Set metadata</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
Sets metadata for the resource. Existing metadata
|
||
items are replaced with the ones provided in the
|
||
request. An overLimit (<errorcode>413</errorcode>)
|
||
fault may be thrown if the maximum number of
|
||
metadata items is exceeded. The maximum number of
|
||
key-value pairs that can be supplied per server is
|
||
determined by the compute provider and may be
|
||
queried via the maxServerMeta absolute limit. The
|
||
maximum number of key-value pairs for an image may
|
||
be queried via the maxImageMeta absolute limit.
|
||
</para>
|
||
<example>
|
||
<title>Metadata Reset Request: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/metadata.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Metadata Reset Request: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/metadata.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Metadata Reset Response: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/metadata.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Metadata Reset Response: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/metadata.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Update_Metadata-d1e5208">
|
||
<title>Update Metadata</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/metadata</td>
|
||
<td colspan="3">Update metadata items</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/images/<parameter>id</parameter>/metadata</td>
|
||
<td colspan="3">Update metadata items</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
Updates resource metadata. Updates will replace
|
||
existing metadata items with the same key. Items
|
||
not explicitly mentioned in the request will not be
|
||
modified. An overLimit (<errorcode>413</errorcode>)
|
||
fault may be thrown if the operation causes the
|
||
maximum number of metadata items to be exceeded.
|
||
The maximum number of key-value pairs that can be
|
||
supplied per server is determined by the compute
|
||
provider and may be queried via the maxServerMeta
|
||
absolute limit. The maximum number of key-value
|
||
pairs for an image may be queried via the
|
||
maxImageMeta absolute limit.
|
||
</para>
|
||
<example>
|
||
<title>Metadata Update Request: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/metadata-update-req.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Metadata Update Request: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/metadata-update-req.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Metadata Update Response: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/metadata-update-resp.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Metadata Update Response: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/metadata-update-resp.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Get_Metadata_Item-d1e5507">
|
||
<title>Get Metadata Item</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/metadata/<parameter>key</parameter></td>
|
||
<td colspan="3">Get metadata item
|
||
associated
|
||
with a server</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/images/<parameter>id</parameter>/metadata/<parameter>key</parameter></td>
|
||
<td colspan="3">Get metadata item
|
||
associated
|
||
with an image</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
Retrieves a single metadata item by key. The
|
||
operation does not require a request body.
|
||
</para>
|
||
<example>
|
||
<title>Metadata Item Response: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/metadata_item.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Metadata Item Response: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/metadata_item.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Create_or_Update_a_Metadata_Item-d1e5633">
|
||
<title>Set Metadata Item</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/metadata/<parameter>key</parameter></td>
|
||
<td colspan="3">Set a metadata item</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/images/<parameter>id</parameter>/metadata/<parameter>key</parameter></td>
|
||
<td colspan="3">Set a metadata item</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
badMediaType (<errorcode>415</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
Sets a metadata item by its key. An overLimit
|
||
(<errorcode>413</errorcode>) fault may be thrown
|
||
if the operation causes the maximum number of
|
||
metadata items to be exceeded. The maximum number
|
||
of key-value pairs that can be supplied per server
|
||
is determined by the compute provider and may be
|
||
queried via the maxServerMeta absolute limit. The
|
||
maximum number of key-value pairs for an image may
|
||
be queried via the maxImageMeta absolute limit.
|
||
</para>
|
||
<example>
|
||
<title>Metadata Item Update Request: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/metadata_item.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Metadata Item Update Request: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/metadata_item.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Metadata Item Update Response: XML </title>
|
||
<programlisting language="xml">
|
||
<xi:include href="samples/metadata_item.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Metadata Item Update Response: JSON </title>
|
||
<programlisting language="javascript">
|
||
<xi:include href="samples/metadata_item.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Delete_Metadata_Item-d1e5790">
|
||
<title>Delete Metadata Item</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&DELETE;</td>
|
||
<td colspan="2">/servers/<parameter>id</parameter>/metadata/<parameter>key</parameter></td>
|
||
<td colspan="3">Deletes a metadata item</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">&DELETE;</td>
|
||
<td colspan="2">/images/<parameter>id</parameter>/metadata/<parameter>key</parameter></td>
|
||
<td colspan="3">Deletes a metadata item</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
computeFault (<errorcode>400</errorcode>, <errorcode>500</errorcode>, …),
|
||
serviceUnavailable (<errorcode>503</errorcode>),
|
||
unauthorized (<errorcode>401</errorcode>),
|
||
forbidden (<errorcode>403</errorcode>),
|
||
badRequest (<errorcode>400</errorcode>),
|
||
badMethod (<errorcode>405</errorcode>),
|
||
overLimit (<errorcode>413</errorcode>),
|
||
itemNotFound (<errorcode>404</errorcode>),
|
||
buildInProgress (<errorcode>409</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
Deletes a metadata item. The operation does not
|
||
require a request body and does not contain a
|
||
response body.
|
||
</para>
|
||
</section>
|
||
</section>
|
||
</chapter>
|
||
</book>
|