From f4efcfb7fab1e2cd8e5141c038998432627547d0 Mon Sep 17 00:00:00 2001 From: Diane Fleming Date: Sun, 22 Sep 2013 14:53:51 -0500 Subject: [PATCH] Added conflictingRequest (409) fault code. bug: #1179500 Change-Id: I66f3ecbb23fc08f6011e67508eaed00cd2fbba3f author: diane fleming --- .../src/os-compute-devguide.xml | 529 +++++++++--------- 1 file changed, 263 insertions(+), 266 deletions(-) diff --git a/openstack-compute-api-2/src/os-compute-devguide.xml b/openstack-compute-api-2/src/os-compute-devguide.xml index 01d509d..c1a99be 100755 --- a/openstack-compute-api-2/src/os-compute-devguide.xml +++ b/openstack-compute-api-2/src/os-compute-devguide.xml @@ -69,7 +69,7 @@ This document is intended for software developers interested in developing applications using the OpenStack Compute Application Programming Interface - (API). + (API). @@ -212,24 +212,24 @@ Added limit and marker - parameters to list operations. + parameters to list operations. The rebuild action behaves just like create: an imageRef is used and a - password may be specified. + password may be specified. Added tenant and user_id attributes - to server and image. + to server and image. Added vcpus attribute to flavors. - + The flavorRef attribute is now used - in the resize action. + in the resize action. @@ -240,79 +240,79 @@ Added missing response examples for - server update. + server update. Ensure consistent HTTP status codes - for all resources. + for all resources. Clarifications on setting and - changing a server password. + changing a server password. Minor updates to metadata section - for clarity. + for clarity. - Discuss alternate links. + Discuss alternate links. Removed version number from compute media types — use a media type - parameter instead. + parameter instead. Bought back the flavorRef and imageRef server attributes these are now only used when creating a server. - + Made the create image operation a - server action. + server action. Added minDisk and minRam filters to - flavor lists. + flavor lists. Added minDisk and minRam attributes - to images. + to images. Asynchronous faults may now contain - a timestamp. + a timestamp. Changes-since request returns an - empty list rather than a 304. + empty list rather than a 304. - Added DELETED image status. + Added DELETED image status. Fix content length in . + />. Fixed bad request error code in . + />. Compact image, server, and flavor lists should contain IDs, names, and links (Any kind of link may be included — not just self links). - + Changed metadata URI from .../meta to .../metadata for consistency. - + @@ -323,7 +323,7 @@ Renamed Primary IP to Access IP. - + @@ -334,71 +334,71 @@ Many minor updates based on - community feedback. + community feedback. Removed sections on Content Compression, Persistent Connections, and Caching — these are operator specific. Added section on HTTP. - + A Location header is returned when - creating servers/images. + creating servers/images. Added filters to collection of - Image, Servers, and Flavors. + Image, Servers, and Flavors. - Added asynchronous faults. + Added asynchronous faults. Updates to links and references. Remove serverRef, imageRef, and flavorRef and instead embed one entity - in another to provide links. + in another to provide links. - Added primary IP addresses. + Added primary IP addresses. - Added forbidden fault. + Added forbidden fault. We now use a single bookmark link per entity regardless of mimetype. - + Collections are now sorted by create - time. + time. Previous links are no longer - required. + required. Added the ability to create or update multiple metadata items - simultaneously. + simultaneously. Minor cleanups to server and image - state machine. + state machine. Update to JSON collection format. - + Replace integer IDs with UUIDs. - + Removed affinityID, this will likely - come in as an extension. + come in as an extension. @@ -410,7 +410,7 @@ Some minor cleanups in preparation for OpenStack Summit discussion. - + @@ -421,31 +421,31 @@ Many minor updates based on - community feedback. + community feedback. Updates to resource linking and - references. + references. Better description of paginated - collections. + collections. Metadata supported in servers and - images. + images. Dropped support for shared IP - groups. + groups. IPs organized by network ID, versus showing only public and private IPs. - + - Generalized affinity ID. + Generalized affinity ID. @@ -455,7 +455,7 @@ - Initial release. + Initial release. @@ -471,17 +471,17 @@ 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. + OpenStack Compute API. We welcome feedback, comments, and bug reports at bugs.launchpad.net/nova. + >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: + should also be familiar with the following concepts: OpenStack Compute service @@ -513,7 +513,7 @@ You can download the most current version of this document from the OpenStack Docs website at - http://docs.openstack.org. + http://docs.openstack.org.
@@ -530,10 +530,10 @@ 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. + 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. + communication between the provider and client users.
Authentication @@ -544,16 +544,16 @@ Auth, Token). The authentication scheme used is determined by the provider of the OpenStack Compute system. Please contact your provider to determine the - best way to authenticate against this API. + best way to authenticate against this API. Some authentication schemes may require that the - API operate using SSL over HTTP (HTTPS). + API operate using SSL over HTTP (HTTPS).
Request/Response Types The OpenStack Compute API supports both JSON and XML - data serialization request and response formats. + data serialization request and response formats. You specify the request format in the Content-Type header in the request. This header is required for operations that have a @@ -600,7 +600,7 @@ from the request format. and show a request body in JSON format and a response body in XML - format. + format. Request with Headers: JSON POST /v2/010101/servers HTTP/1.1 @@ -631,7 +631,7 @@ Server: Jetty(8.0.y.z-SNAPSHOT) an Accept header to request an XML response. - The XML response is not shown. + The XML response is not shown. JSON Request with XML Query Extension for the @@ -652,7 +652,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout> 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> + deployment.</para> <?hard-pagebreak?> <example> <title>ID Image Reference: JSON @@ -696,7 +696,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb Note that the type attribute here is used to provide a hint as to the type of - representation to expect when following the link. + representation to expect when following the link. @@ -738,7 +738,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb which is supported by the deployment an overLimit (413) fault may be thrown. A marker with an invalid ID will return a badRequest - (400) fault. + (400) fault. 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 @@ -751,7 +751,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb Subsequent links will honor the initial page size. Thus, a client may follow links to traverse a paginated collection without having to input the - marker parameter. + marker parameter. Images Collection, First Page: XML @@ -797,7 +797,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb 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. + of metadata. Paginated Metadata in an Image: XML @@ -839,7 +839,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb &GET; against https://api.servers.openstack.org/v2/224532/servers?changes-since=2011-01-24T17:08Z would list all servers that have changed since Mon, 24 - Jan 2011 17:08:00 UTC. + Jan 2011 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 @@ -848,7 +848,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb Implementations are not required to keep track of deleted resources indefinitely, so sending a changes since time in the distant past may miss deletions. - +
@@ -866,7 +866,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb limits that apply to your account or see . Your provider may be able to adjust your account's limits if they are - too low. + too low.
Rate Limits Rate limits are specified in terms of both a @@ -875,14 +875,14 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb human-readable limit is intended for displaying in graphical user interfaces. The machine-processable form is intended to be used directly by client - applications. + 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. + role="bold">/servers. @@ -932,13 +932,13 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb */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. + 10/min.In the event a request exceeds the thresholds established for your account, a 413 HTTP response will be returned with a Retry-After header to notify the client when they can attempt to try - again. + again.
@@ -952,7 +952,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb 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. + metadata items.
Sample Rate Limits
@@ -1002,7 +1002,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbbDetermining Limits ProgrammaticallyApplications can programmatically determine current account limits using the /limits URI as - follows: + follows: @@ -1060,7 +1060,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb 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. + URI, the URI takes precedence. Request with MIME type versioning @@ -1084,13 +1084,13 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb 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) will follow - providing links and MIME types to available versions. + providing links and MIME types to available versions. Multiple Choices Response: XML @@ -1112,7 +1112,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb versions will be 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. + 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 @@ -1122,7 +1122,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb when issuing a request with the Accept header containing application/atom+xml or by adding a .atom to the request URI. This allows standard Atom - clients to track version changes. + clients to track version changes. Versions List Request @@ -1169,7 +1169,7 @@ Host: servers.api.openstack.org 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. + equivalently. Version Details Request @@ -1210,12 +1210,12 @@ Host: servers.api.openstack.org/v2/ 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). + Application Description Language (WADL). If a discrepancy exists between the two References, the WADL is authoritative as it contains the most accurate and up-to-date - description of the API service. + description of the API service.
Sample Absolute Limits