From ffc4cedb2be6eb94caa352189bbf1e747c5ed515 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Wed, 17 Dec 2014 10:14:37 -0600 Subject: [PATCH] Adds Compute API v2 docs Imported from public API docs plus fixes to make them more accurate. Change-Id: I6d5ba6b96772e0f17fc7484312222110ec103bbf --- doc/source/index.rst | 9 + doc/source/v2/2.0_general_info.rst | 121 +++++++++ doc/source/v2/2.0_server_concepts.rst | 235 ++++++++++++++++++ doc/source/v2/authentication.rst | 14 ++ doc/source/v2/extensions.rst | 149 +++++++++++ doc/source/v2/faults.rst | 190 ++++++++++++++ doc/source/v2/index.rst | 25 ++ doc/source/v2/limits.rst | 94 +++++++ doc/source/v2/links_and_references.rst | 124 +++++++++ doc/source/v2/paginated_collections.rst | 105 ++++++++ .../v2/polling_changes-since_parameter.rst | 29 +++ .../v2/request_and_response_formats.rst | 86 +++++++ doc/source/v2/versions.rst | 130 ++++++++++ 13 files changed, 1311 insertions(+) create mode 100644 doc/source/v2/2.0_general_info.rst create mode 100644 doc/source/v2/2.0_server_concepts.rst create mode 100644 doc/source/v2/authentication.rst create mode 100644 doc/source/v2/extensions.rst create mode 100644 doc/source/v2/faults.rst create mode 100644 doc/source/v2/index.rst create mode 100644 doc/source/v2/limits.rst create mode 100644 doc/source/v2/links_and_references.rst create mode 100644 doc/source/v2/paginated_collections.rst create mode 100644 doc/source/v2/polling_changes-since_parameter.rst create mode 100644 doc/source/v2/request_and_response_formats.rst create mode 100644 doc/source/v2/versions.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index af1c1567bb..8890600380 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -50,6 +50,15 @@ Developer Docs man/index support-matrix +Compute API v2 +============== + +.. toctree:: + :glob: + :maxdepth: 1 + + v2/* + API Extensions ============== diff --git a/doc/source/v2/2.0_general_info.rst b/doc/source/v2/2.0_general_info.rst new file mode 100644 index 0000000000..e32e3e83ae --- /dev/null +++ b/doc/source/v2/2.0_general_info.rst @@ -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 `__. + +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)* `__. + +For information about Compute API v 2 extensions, see the `*Compute API v2 +extensions +(CURRENT)* `__. + diff --git a/doc/source/v2/2.0_server_concepts.rst b/doc/source/v2/2.0_server_concepts.rst new file mode 100644 index 0000000000..b4e3f8d2b0 --- /dev/null +++ b/doc/source/v2/2.0_server_concepts.rst @@ -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" + } + } diff --git a/doc/source/v2/authentication.rst b/doc/source/v2/authentication.rst new file mode 100644 index 0000000000..65ae75815c --- /dev/null +++ b/doc/source/v2/authentication.rst @@ -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). + diff --git a/doc/source/v2/extensions.rst b/doc/source/v2/extensions.rst new file mode 100644 index 0000000000..26c93f091b --- /dev/null +++ b/doc/source/v2/extensions.rst @@ -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" + } + } + diff --git a/doc/source/v2/faults.rst b/doc/source/v2/faults.rst new file mode 100644 index 0000000000..3c269985f2 --- /dev/null +++ b/doc/source/v2/faults.rst @@ -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" + } + ] + } + } diff --git a/doc/source/v2/index.rst b/doc/source/v2/index.rst new file mode 100644 index 0000000000..9cef212ecd --- /dev/null +++ b/doc/source/v2/index.rst @@ -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: diff --git a/doc/source/v2/limits.rst b/doc/source/v2/limits.rst new file mode 100644 index 0000000000..8229d5ee5b --- /dev/null +++ b/doc/source/v2/limits.rst @@ -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* `__. + +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* `__. diff --git a/doc/source/v2/links_and_references.rst b/doc/source/v2/links_and_references.rst new file mode 100644 index 0000000000..20676aac84 --- /dev/null +++ b/doc/source/v2/links_and_references.rst @@ -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" + } + ] + } + } diff --git a/doc/source/v2/paginated_collections.rst b/doc/source/v2/paginated_collections.rst new file mode 100644 index 0000000000..e72c3ed7ce --- /dev/null +++ b/doc/source/v2/paginated_collections.rst @@ -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" + } + ] + } + } + diff --git a/doc/source/v2/polling_changes-since_parameter.rst b/doc/source/v2/polling_changes-since_parameter.rst new file mode 100644 index 0000000000..eef1e42b0f --- /dev/null +++ b/doc/source/v2/polling_changes-since_parameter.rst @@ -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 `__ 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. + diff --git a/doc/source/v2/request_and_response_formats.rst b/doc/source/v2/request_and_response_formats.rst new file mode 100644 index 0000000000..ecceb58722 --- /dev/null +++ b/doc/source/v2/request_and_response_formats.rst @@ -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" + } + ] + } + } + diff --git a/doc/source/v2/versions.rst b/doc/source/v2/versions.rst new file mode 100644 index 0000000000..215017d31b --- /dev/null +++ b/doc/source/v2/versions.rst @@ -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* +`__. + +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). +