openstack/nova
Code Issues Proposed changes

Adds Compute API v2 docs

Browse Source 
Imported from public API docs plus fixes to make them more accurate.

Change-Id: I6d5ba6b96772e0f17fc7484312222110ec103bbf
This commit is contained in:
Anne Gentle
2014-12-17 10:14:37 -06:00
parent 0e148b1ef4
commit ffc4cedb2b
13 changed files with 1311 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
doc/source/index.rst
View File

@@ -50,6 +50,15 @@ Developer Docs
man/index
support-matrix
Compute API v2
==============
.. toctree::
:glob:
:maxdepth: 1
v2/*
API Extensions
==============

121
doc/source/v2/2.0_general_info.rst Normal file
View File

@@ -0,0 +1,121 @@
====================================
General Compute API v2.0 information
====================================
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.
Providers can return information identifying requests in HTTP response
headers, for example, to facilitate communication between the provider
and client users.
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 happen programmatically with the OpenStack
Compute API.
We welcome feedback, comments, and bug reports at
`bugs.launchpad.net/nova <http://bugs.launchpad.net/nova>`__.
Intended audience
-----------------
This guide assists software developers who want to develop applications
using the OpenStack Compute API. To use this information, you should
have access to an account from an OpenStack Compute provider, and you
should also be familiar with the following concepts:
- OpenStack Compute service
- ReSTful web services
- HTTP/1.1
- JSON data serialization formats
Concepts
--------
To use the OpenStack Compute API effectively, you should understand
several key concepts:
- **Server**
A virtual machine (VM) instance in the compute system. Flavor and
image are requisite elements when creating a server.
- **Flavor**
An available hardware configuration for a server. Each flavor has a
unique combination of disk space, memory capacity and priority for
CPU time.
- **Image**
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.
- **Reboot**
Use this function to perform either a soft or hard reboot of a
server. With a soft reboot, the operating system is signaled to
restart, which allows for a graceful shutdown of all processes. A
hard reboot is the equivalent of power cycling the server. The
virtualization platform should ensure that the reboot action has
completed successfully even in cases in which the underlying
domain/VM is paused or halted/stopped.
- **Rebuild**
Use this function to remove all data on the server and replaces it
with the specified image. Server ID and IP addresses remain the same.
- **Resize**
Use this function to convert an existing server to a different
flavor, in essence, scaling the server up or down. The original
server is saved for a period of time to allow rollback if there is a
problem. All resizes should be tested and explicitly confirmed, at
which time the original server is removed. All resizes are
automatically confirmed after 24 hours if you do not confirm or
revert them.
- **Pause**
You can pause a server by making a pause request. This request stores
the state of the VM in RAM. A paused instance continues to run in a
frozen state.
- **Suspend**
Administrative users might want to suspend an instance if it is
infrequently used or to perform system maintenance. When you suspend
an instance, its VM state is stored on disk, all memory is written to
disk, and the virtual machine is stopped. Suspending an instance is
similar to placing a device in hibernation; memory and vCPUs become
available to create other instances.
Reference
---------
For a reference listing for the Compute API v2, see the `*Compute API v2
reference
(CURRENT)* <http://developer.openstack.org/api-ref-compute-v2.html>`__.
For information about Compute API v 2 extensions, see the `*Compute API v2
extensions
(CURRENT)* <http://developer.openstack.org/api-ref-compute-v2-ext.html>`__.

235
doc/source/v2/2.0_server_concepts.rst Normal file
View File

@@ -0,0 +1,235 @@
===============
Server concepts
===============
For the OpenStack Compute API, a server is a virtual machine (VM) instance in
the compute system.
Server status
~~~~~~~~~~~~~
You can filter the list of servers by image, flavor, name, and status
through the respective query parameters.
Servers contain a status attribute that indicates the current server
state. You can filter on the server status when you complete a list
servers request. The server status is returned in the response body. The
server status is one of the following values:
**Server status values**
- ``ACTIVE``: The server is active.
- ``BUILD``: The server has not finished the original build process.
- ``DELETED``: The server is deleted.
- ``ERROR``: The server is in error.
- ``HARD_REBOOT``: The server is hard rebooting. This is equivalent to
pulling the power plug on a physical server, plugging it back in, and
rebooting it.
- ``PASSWORD``: The password is being reset on the server.
- ``REBOOT``: The server is in a soft reboot state. A reboot command
was passed to the operating system.
- ``REBUILD``: The server is currently being rebuilt from an image.
- ``RESCUE``: The server is in rescue mode.
- ``RESIZE``: Server is performing the differential copy of data that
changed during its initial copy. Server is down for this stage.
- ``REVERT_RESIZE``: The resize or migration of a server failed for
some reason. The destination server is being cleaned up and the
original source server is restarting.
- ``SHUTOFF``: The virtual machine (VM) was powered down by the user,
but not through the OpenStack Compute API. For example, the user
issued a ``shutdown -h`` command from within the server instance. If
the OpenStack Compute manager detects that the VM was powered down,
it transitions the server instance to the SHUTOFF status. If you use
the OpenStack Compute API to restart the instance, the instance might
be deleted first, depending on the value in the
*``shutdown_terminate``* database field on the Instance model.
- ``SUSPENDED``: The server is suspended, either by request or
necessity. This status appears for only the following hypervisors:
XenServer/XCP, KVM, and ESXi. Administrative users may suspend an
instance if it is infrequently used or to perform system maintenance.
When you suspend an instance, its VM state is stored on disk, all
memory is written to disk, and the virtual machine is stopped.
Suspending an instance is similar to placing a device in hibernation;
memory and vCPUs become available to create other instances.
- ``UNKNOWN``: The state of the server is unknown. Contact your cloud
provider.
- ``VERIFY_RESIZE``: System is awaiting confirmation that the server is
operational after a move or resize.
The compute provisioning algorithm has an anti-affinity property that
attempts to spread customer VMs across hosts. Under certain situations,
VMs from the same customer might be placed on the same host. hostId
represents the host your server runs on and can be used to determine
this scenario if it is relevant to your application.
.. note:: HostId is unique *per account* and is not globally unique.
Server creation
~~~~~~~~~~~~~~~
Status Transition:
``BUILD``
``ACTIVE``
``BUILD``
``ERROR`` (on error)
When you create a server, the 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/*``id``*, which returns a progress
attribute (from 0% to 100% complete). The full URL to the newly created
server is returned through the ``Location`` header and is available as a
``self`` and ``bookmark`` link in the server representation. Note that
when creating a server, only the server ID, its links, and the
administrative password are guaranteed to be returned in the request.
You can retrieve additional attributes by performing subsequent **GET**
operations on the server.
Server passwords
~~~~~~~~~~~~~~~~
You can specify a password when you create the server through the
optional adminPass attribute. The specified password must meet the
complexity requirements set by your OpenStack Compute provider. The
server might enter an ``ERROR`` state if the complexity requirements are
not met. In this case, a client can issue a change password action to
reset the server password.
If a password is not specified, a randomly generated password is
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 is not returned in
subsequent **GET** calls.
Server metadata
~~~~~~~~~~~~~~~
Custom server metadata can also be supplied at launch time. 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.
Server networks
~~~~~~~~~~~~~~~
Networks to which the server connects can also be supplied at launch
time. One or more networks can be specified. User can also specify a
specific port on the network or the fixed IP address to assign to the
server interface.
Server personality
~~~~~~~~~~~~~~~~~~
You can customize the personality of a server instance by injecting data
into its file system. For example, you might want to insert ssh keys,
set configuration files, or store data that you want to retrieve from
inside the instance. This feature provides a minimal amount of
launch-time personalization. If you require significant customization,
create a custom image.
Follow these guidelines when you inject files:
- The maximum size of the file path data is 255 bytes.
- Encode the file contents as a Base64 string. The maximum 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
Considerations
~~~~~~~~~~~~~~
The maximum limit refers to the number of bytes in the decoded data
and not the number of characters in the encoded data.
- You can inject text files only. You cannot inject binary or zip files
into a new build.
- The maximum number of file path/content pairs that you can supply is
also determined by the compute provider and is defined by the
maxPersonality absolute limit.
- The absolute limit, maxPersonalitySize, is a byte limit that is
guaranteed to apply to all images in the deployment. Providers can
set additional per-image personality limits.
The file injection might not occur until after the server is built and
booted.
During file injection, any existing files that match specified files are
renamed to include the BAK extension appended with a time stamp. For
example, if the ``/etc/passwd`` file exists, it is backed up as
``/etc/passwd.bak.1246036261.5785``.
After file injection, personality files are accessible by only system
administrators. For example, on Linux, all files have root and the root
group as the owner and group owner, respectively, and allow user and
group read access only (octal 440).
Server access addresses
~~~~~~~~~~~~~~~~~~~~~~~
In a hybrid environment, the IP address of a server might not be
controlled by the underlying implementation. Instead, the access IP
address might 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 *access address* 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.
Nonetheless, clients that must 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.
**Example: Create server with access IP: JSON request**
.. code::
{
"server":{
"name":"new-server-test",
"imageRef":"52415800-8b69-11e0-9b19-734f6f006e54",
"flavorRef":"52415800-8b69-11e0-9b19-734f1195ff37",
"accessIPv4":"67.23.10.132"
}
}
.. note:: 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.
**Example: Create server with multiple access IPs: JSON request**
.. code::
{
"server":{
"name":"new-server-test",
"imageRef":"52415800-8b69-11e0-9b19-734f6f006e54",
"flavorRef":"52415800-8b69-11e0-9b19-734f1195ff37",
"accessIPv4":"67.23.10.132",
"accessIPv6":"::babe:67.23.10.132"
}
}

14
doc/source/v2/authentication.rst Normal file
View File

@@ -0,0 +1,14 @@
==============
Authentication
==============
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 is provided by the OpenStack Identity service.
You can contact your provider to determine the best way to authenticate against
the Compute API.
.. note:: Some authentication schemes may require that the API operate using
SSL over HTTP (HTTPS).

149
doc/source/v2/extensions.rst Normal file
View File

@@ -0,0 +1,149 @@
==========
Extensions
==========
The OpenStack Compute API v2.0 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 list available
extensions by performing a **GET** on the ``/extensions`` URI. Note that
this is a versioned request; that is, an extension available in one API
version might not be available in another.
Extensions may also be queried individually by their unique alias. This
provides the simplest method of checking if an extension is available
because an unavailable extension issues an itemNotFound (404) response.
Extensions may define new data types, parameters, actions, headers,
states, and resources. In XML, additional elements and attributes can be
defined. These elements must be defined in the namespace for the
extension. In JSON, the alias must be used. The volumes element is
defined in the ``RS-CBS`` namespace. Extended headers are always
prefixed with ``X-`` followed by the alias and a dash:
(``X-RS-CBS-HEADER1``). States and parameters must be prefixed with the
extension alias followed by a colon. For example, an image might be in
the ``RS-PIE:PrepareShare`` state.
Important
~~~~~~~~~
Applications should ignore response data that contains extension
elements. An extended state should always be treated as an ``UNKNOWN``
state if the application does not support the extension. Applications
should also verify that an extension is available before submitting an
extended request.
**Example: Extended server: JSON response**
.. code::
{
"servers": [
{
"id": "52415800-8b69-11e0-9b19-734f6af67565",
"tenant_id": "1234",
"user_id": "5678",
"name": "sample-server",
"updated": "2010-10-10T12:00:00Z",
"created": "2010-08-10T12:00:00Z",
"hostId": "e4d909c290d0fb1ca068ffaddf22cbd0",
"status": "BUILD",
"progress": 60,
"accessIPv4" : "67.23.10.132",
"accessIPv6" : "::babe:67.23.10.132",
"image" : {
"id": "52415800-8b69-11e0-9b19-734f6f006e54",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
}
]
},
"flavor" : {
"id": "52415800-8b69-11e0-9b19-734f216543fd",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
}
]
},
"addresses": {
"public" : [
{
"version": 4,
"addr": "67.23.10.132"
},
{
"version": 6,
"addr": "::babe:67.23.10.132"
},
{
"version": 4,
"addr": "67.23.10.131"
},
{
"version": 6,
"addr": "::babe:4317:0A83"
}
],
"private" : [
{
"version": 4,
"addr": "10.176.42.16"
},
{
"version": 6,
"addr": "::babe:10.176.42.16"
}
]
},
"metadata": {
"Server Label": "Web Head 1",
"Image Version": "2.1"
},
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
}
],
"RS-CBS:volumes": [
{
"name": "OS",
"href": "https://cbs.api.rackspacecloud.com/12934/volumes/19"
},
{
"name": "Work",
"href": "https://cbs.api.rackspacecloud.com/12934/volumes/23"
}
]
}
]
}
**Example: Extended action: JSON response**
.. code::
{
"RS-CBS:attach-volume":{
"href":"https://cbs.api.rackspacecloud.com/12934/volumes/19"
}
}

190
doc/source/v2/faults.rst Normal file
View File

@@ -0,0 +1,190 @@
======
Faults
======
Synchronous faults
~~~~~~~~~~~~~~~~~~
When an error occurs at request time, the system also returns additional
information about the fault in the body of the response.
**Example: Fault: JSON response**
.. code::
{
"computeFault":{
"code":500,
"message":"Fault!",
"details":"Error Details..."
}
}
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 might or might not be appropriate for
display to an end user.
The root element of the fault (such as, computeFault) might change
depending on the type of error. The following is a list of possible
elements along with their associated error codes.
Fault elements and error codes
------------------------------
- ``computeFault``: 500, 400, other codes possible
- ``notImplemented``: 501
- ``serverCapacityUnavailable``: 503
- ``serviceUnavailable``: 503
- ``badRequest``: 400
- ``unauthorized``: 401
- ``forbidden``: 403
- ``resizeNotAllowed``: 403
- ``itemNotFound``: 404
- ``badMethod``: 405
- ``backupOrResizeInProgress``: 409
- ``buildInProgress``: 409
- ``conflictingRequest``: 409
- ``overLimit``: 413
- ``badMediaType``: 415
**Example: Item Not Found fault: JSON response**
.. code::
{
"itemNotFound":{
"code":404,
"message":"Not Found",
"details":"Error Details..."
}
}
From an XML schema perspective, all API faults are extensions of the
base ComputeAPIFault fault type. When working with a system that binds
XML to actual classes (such as JAXB), you should use ComputeAPIFault as
a catch-all if you do not want to distinguish between individual fault
types.
The OverLimit fault is generated when a rate limit threshold is
exceeded. For convenience, the fault adds a retryAfter attribute that
contains the content of the Retry-After header in XML Schema 1.0
date/time format.
**Example: Over Limit fault: JSON response**
.. code::
{
"overLimit" : {
"code" : 413,
"message" : "OverLimit Retry...",
"details" : "Error Details...",
"retryAfter" : "2010-08-01T00:00:00Z"
}
}
Asynchronous faults
~~~~~~~~~~~~~~~~~~~
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 ``ERROR`` 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 occurred.
**Example: Server in error state: JSON response**
.. code::
{
"server": {
"id": "52415800-8b69-11e0-9b19-734f0000ffff",
"tenant_id": "1234",
"user_id": "5678",
"name": "sample-server",
"created": "2010-08-10T12:00:00Z",
"hostId": "e4d909c290d0fb1ca068ffafff22cbd0",
"status": "ERROR",
"progress": 66,
"image" : {
"id": "52415800-8b69-11e0-9b19-734f6f007777"
},
"flavor" : {
"id": "52415800-8b69-11e0-9b19-734f216543fd"
},
"fault" : {
"code" : 404,
"created": "2010-08-10T11:59:59Z",
"message" : "Could not find image 52415800-8b69-11e0-9b19-734f6f007777",
"details" : "Fault details"
},
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f000004d2"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f000004d2"
}
]
}
}
**Example: Image in error state: JSON response**
.. code::
{
"image" : {
"id" : "52415800-8b69-11e0-9b19-734f5736d2a2",
"name" : "My Server Backup",
"created" : "2010-08-10T12:00:00Z",
"status" : "SAVING",
"progress" : 89,
"server" : {
"id": "52415800-8b69-11e0-9b19-734f335aa7b3"
},
"fault" : {
"code" : 500,
"message" : "An internal error occurred",
"details" : "Error details"
},
"links": [
{
"rel" : "self",
"href" : "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
},
{
"rel" : "bookmark",
"href" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
}
]
}
}

25
doc/source/v2/index.rst Normal file
View File

@@ -0,0 +1,25 @@
..
Copyright 2009-2014 OpenStack Foundation
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Compute API v2
==============
This section describes the Compute API version 2 and is intended for software
developers interested in developing applications using the OpenStack Compute
Application Programming Interface (API).
..toctree::
:maxdepth: 3
:glob:

94
doc/source/v2/limits.rst Normal file
View File

@@ -0,0 +1,94 @@
======
Limits
======
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: *rate limits* and *absolute limits*. 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. Your provider may be able to adjust your
account's limits if they are too low. Also see the API Reference for
`*Limits* <http://developer.openstack.org/api-ref-compute-v2.html#compute_limits>`__.
Rate limits
~~~~~~~~~~~
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.
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/v2/3542812\ **/servers**.
**Table: Sample rate limits**
+------------+-------------------+----------------------+----------+
| Verb | URI | RegEx | Default |
+------------+-------------------+----------------------+----------+
| **POST** | \* | .\* | 120/min |
+------------+-------------------+----------------------+----------+
| **POST** | \*/servers | ^/servers | 120/min |
+------------+-------------------+----------------------+----------+
| **PUT** | \* | .\* | 120/min |
+------------+-------------------+----------------------+----------+
| **GET** | \*changes-since\* | .\*changes-since.\* | 120/min |
+------------+-------------------+----------------------+----------+
| **DELETE** | \* | .\* | 120/min |
+------------+-------------------+----------------------+----------+
| **GET** | \*/os-fping\* | ^/os-fping | 12/min |
+------------+-------------------+----------------------+----------+
Rate limits are applied in order relative to the verb, going from least
to most specific.
In the event a request exceeds the thresholds established for your
account, a 413 HTTP response is returned with a ``Retry-After`` header
to notify the client when they can attempt to try again.
Absolute limits
~~~~~~~~~~~~~~~
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.
**Table: Sample absolute limits**
+-------------------+-------------------+------------------------------------+
| Name | Value | Description |
+-------------------+-------------------+------------------------------------+
| maxTotalRAMSize | 51200 | Maximum total amount of RAM (MB) |
+-------------------+-------------------+------------------------------------+
| maxServerMeta | 5 | Maximum number of metadata items |
| | | associated with a server. |
+-------------------+-------------------+------------------------------------+
| maxImageMeta | 5 | Maximum number of metadata items |
| | | associated with an image. |
+-------------------+-------------------+------------------------------------+
| maxPersonality | 5 | The maximum number of file |
| | | path/content pairs that can be |
| | | supplied on server build. |
+-------------------+-------------------+------------------------------------+
| maxPersonalitySize| 10240 | The maximum size, in bytes, for |
| | | each personality file. |
+-------------------+-------------------+------------------------------------+
Determine limits programmatically
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Applications can programmatically determine current account limits. For
information, see
`*Limits* <http://developer.openstack.org/api-ref-compute-v2.html#compute_limits>`__.

124
doc/source/v2/links_and_references.rst Normal file
View File

@@ -0,0 +1,124 @@
====================
Links and references
====================
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.
**Example: ID image reference: JSON request**
.. code::
{
"server":{
"flavorRef":"http://openstack.example.com/openstack/flavors/1",
"imageRef":"http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
"metadata":{
"My Server Name":"Apache1"
},
"name":"new-server-test",
"personality":[
{
"contents":"ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
"path":"/etc/banner.txt"
}
]
}
}
**Example: Full image reference: JSON request**
.. code::
{
"server": {
"name": "server-test-1",
"imageRef": "b5660a6e-4b46-4be3-9707-6b47221b454f",
"flavorRef": "2",
"max_count": 1,
"min_count": 1,
"networks": [
{
"uuid": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
}
],
"security_groups": [
{
"name": "default"
},
{
"name": "another-secgroup-name"
}
]
}
}
For convenience, resources contain links to themselves. This allows a
client to easily obtain rather than construct resource URIs. The
following types of link relations are associated with resources:
- A ``self`` link contains a versioned link to the resource. Use these
links when the link is followed immediately.
- A ``bookmark`` link provides a permanent link to a resource that is
appropriate for long term storage.
- An ``alternate`` link can contain an alternate representation of the
resource. For example, an OpenStack Compute image might have an
alternate representation in the OpenStack Image service.
.. note:: The type attribute provides a hint as to the type of representation
to expect when following the link.
**Example: Server with self links: JSON**
.. code::
{
"server":{
"id":"52415800-8b69-11e0-9b19-734fcece0043",
"name":"my-server",
"links":[
{
"rel":"self",
"href":"http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"
},
{
"rel":"bookmark",
"href":"http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734fcece0043"
}
]
}
}
**Example: Server with alternate link: JSON**
.. code::
{
"image" : {
"id" : "52415800-8b69-11e0-9b19-734f5736d2a2",
"name" : "My Server Backup",
"links": [
{
"rel" : "self",
"href" : "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
},
{
"rel" : "bookmark",
"href" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
},
{
"rel" : "alternate",
"type" : "application/vnd.openstack.image",
"href" : "http://glance.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
}
]
}
}

105
doc/source/v2/paginated_collections.rst Normal file
View File

@@ -0,0 +1,105 @@
=====================
Paginated collections
=====================
To reduce load on the service, list operations 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 *``limit``* and
*``marker``* parameters can be set in the URI. For example:
.. code::
?limit=100&marker=1234
The *``marker``* parameter is the ID of the last item in the previous
list. By default, the service sorts items by create time in descending order.
When the service cannot identify a a create time, it sorts items by ID. The
*``limit``* parameter sets the page size. Both parameters are optional. If the
client requests a *``limit``* beyond that which is supported by the deployment
an overLimit (413) fault may be thrown. A marker with an invalid ID returns
a badRequest (400) fault.
For convenience, collections should contain atom ``next``
links. They may optionally also contain ``previous`` links but the current
implementation does not contain ``previous`` links. The last
page in the list does not contain a "next" link. The following examples
illustrate three pages in a collection of images. The first page was
retrieved through a **GET** to
``http://servers.api.openstack.org/v2/1234/servers?limit=1``. In these
examples, the *``limit``* parameter sets the page size to a single item.
Subsequent links honor the initial page size. Thus, a client can follow
links to traverse a paginated collection without having to input the
*``marker``* parameter.
**Example: Servers collection: JSON (first page)**
.. code::
{
"servers_links":[
{
"href":"https://servers.api.openstack.org/v2/1234/servers?limit=1&marker=fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"next"
}
],
"servers":[
{
"id":"fc55acf4-3398-447b-8ef9-72a42086d775",
"links":[
{
"href":"https://servers.api.openstack.org/v2/1234/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"self"
},
{
"href":"https://servers.api.openstack.org/v2/1234/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"bookmark"
}
],
"name":"elasticsearch-0"
}
]
}
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
``links``. 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.
**Example: Paginated metadata: JSON**
.. code::
{
"server": {
"id": "52415800-8b69-11e0-9b19-734f6f006e54",
"name": "Elastic",
"metadata": {
"Version": "1.3",
"ServiceType": "Bronze"
},
"metadata_links": [
{
"rel": "next",
"href": "https://servers.api.openstack.org/v2/1234/servers/fc55acf4-3398-447b-8ef9-72a42086d775/meta?marker=ServiceType"
}
],
"links": [
{
"rel": "self",
"href": "https://servers.api.openstack.org/v2/1234/servers/fc55acf4-3398-447b-8ef9-72a42086d775"
}
]
}
}

29
doc/source/v2/polling_changes-since_parameter.rst Normal file
View File

@@ -0,0 +1,29 @@
==================================================
Efficient polling with the Changes-Since parameter
==================================================
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 *``changes-since``* parameter to check for changes since a
previous request. The *``changes-since``* time is specified as an `ISO
8601 <http://en.wikipedia.org/wiki/ISO_8601>`__ 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 is assumed. If
nothing has changed since the *``changes-since``* time, an empty list is
returned. If data has changed, only the items changed since the
specified time are returned in the response. For example, performing a
**GET** against
https://api.servers.openstack.org/v2/224532/servers?\ *``changes-since``*\ =2015-01-24T17:08Z
would list all servers that have changed since Mon, 24 Jan 2015 17:08:00
UTC.
To allow clients to keep track of changes, the changes-since filter
displays items that have been *recently* deleted. Both images and
servers contain a ``DELETED`` 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.

86
doc/source/v2/request_and_response_formats.rst Normal file
View File

@@ -0,0 +1,86 @@
============================
Request and response formats
============================
The OpenStack Compute API supports JSON request and response formats.
Request format
~~~~~~~~~~~~~~
Use the ``Content-Type`` request header to specify the request format.
This header is required for operations that have a request body.
The syntax for the ``Content-Type`` header is:
.. code::
Content-Type: application/FORMAT
Where ``FORMAT`` is ``json``.
Response format
~~~~~~~~~~~~~~~
Use one of the following methods to specify the response format:
``Accept`` header
The syntax for the ``Accept`` header is:
.. code::
Accept: application/FORMAT
Where *``FORMAT``* is ``json`` and the default format is ``json``.
Query extension
Add a ``.json`` extension to the request URI. For example, the ``.json`` extension in the following list servers URI request specifies that the response body is to be returned in JSON format:
**GET** *``publicURL``*/servers.json
If you do not specify a response format, JSON is the default.
Request and response examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can serialize a response in a different format from the request
format.
The examples below show a request body in JSON format.
.. note:: Though you may find outdated documents with XML examples, XML support
in requests and responses has been deprecated for the Compute API v2
(stable) and v2.1 (experimental).
**Example: JSON request with headers**
| POST /v2/010101/servers HTTP/1.1
| Host: servers.api.openstack.org
| Content-Type: application/json
| Accept: application/xml
| X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
.. code::
{
"server": {
"name": "server-test-1",
"imageRef": "b5660a6e-4b46-4be3-9707-6b47221b454f",
"flavorRef": "2",
"max_count": 1,
"min_count": 1,
"networks": [
{
"uuid": "d32019d3-bc6e-4319-9c1d-6722fc136a22"
}
],
"security_groups": [
{
"name": "default"
},
{
"name": "another-secgroup-name"
}
]
}
}

130
doc/source/v2/versions.rst Normal file
View File

@@ -0,0 +1,130 @@
========
Versions
========
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/
v2.0/...). The MIME type versioning scheme uses HTTP content negotiation
where the ``Accept`` or ``Content-Type`` headers contains a MIME type
that identifies the version (application/vnd.openstack.compute.v2+xml).
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.
**Example: Request with MIME type versioning**
.. code::
GET /214412/images HTTP/1.1
Host: servers.api.openstack.org
Accept: application/vnd.openstack.compute.v2+xml
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
**Example: Request with URI versioning**
.. code::
GET /v2/214412/images HTTP/1.1
Host: servers.api.openstack.org
Accept: application/xml
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Permanent Links
~~~~~~~~~~~~~~~
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.
If a request is made without a version specified in the URI or via HTTP
headers, then a multiple-choices response (300) follows that provides
links and MIME types to available versions.
**Example: Multiple choices: JSON response**
.. code::
{
"choices":[
{
"id":"v1.0",
"status":"DEPRECATED",
"links":[
{
"rel":"self",
"href":"http://servers.api.openstack.org/v1.0/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
}
],
"media-types":[
{
"base":"application/xml",
"type":"application/vnd.openstack.compute.v1.0+xml"
},
{
"base":"application/json",
"type":"application/vnd.openstack.compute.v1.0+json"
}
]
},
{
"id":"v2",
"status":"CURRENT",
"links":[
{
"rel":"self",
"href":"http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
}
],
"media-types":[
{
"base":"application/xml",
"type":"application/vnd.openstack.compute.v2+xml"
},
{
"base":"application/json",
"type":"application/vnd.openstack.compute.v2+json"
}
]
}
]
}
New features and functionality that do not break API-compatibility are
introduced in the current version of the API as extensions and the URI and MIME
types remain unchanged. Features or functionality changes that would necessitate a break in API-compatibility require a new version, which results
in URI and MIME type version being updated accordingly. When new API versions
are released, older versions are marked as ``DEPRECATED``. Providers should
work with developers and partners to ensure there is adequate time to
migrate to the new version before deprecated versions are discontinued.
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.
You can also obtain additional information about a specific version by
performing a **GET** on the base version URL (such as,
``https://servers.api.openstack.org/v2/``). Version request URLs must
always end with a trailing slash (``/``). If you omit the slash, the
server might respond with a 302 redirection request. Format extensions
can be placed after the slash (such as,
``https://servers.api.openstack.org/v2/.json``).
.. note:: This special case does not hold true for other API requests. In
general, requests such as ``/servers.json`` and ``/servers/.json`` are
handled equivalently.
For examples of the list versions and get version details requests and
responses, see `*API versions*
<http://developer.openstack.org/api-ref-compute-v2.html#compute_versions>`__.
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).