From 2ab480d9700b6999a6bf11f22548de066922da1f Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Fri, 1 Aug 2014 22:15:29 -0500 Subject: [PATCH] Replaces WADL references with links to API Reference - Moves detailed info to the Compute API v2 WADL itself - Alleviates the following issues: * Params are not documented in this output due to tooling * When a WADL was broken, this deliverable breaks also * WADL contributions are low * It's difficult to train contributors how to embed WADL references Change-Id: Id56da05c0409ed432dfdd0f5de799f5ed5e2e47c --- v2/bk_compute_api_ref_v2.xml | 1695 ++++++++----------------- v2/pom.xml | 14 +- v2/samples/choices.json | 86 +- v2/samples/fault.json | 12 +- v2/samples/image-fault.xml | 18 +- v2/samples/image-meta-page1.xml | 21 +- v2/samples/image-simple.xml | 18 +- v2/samples/images-page1.xml | 5 +- v2/samples/images-page2.xml | 13 +- v2/samples/images-page3.xml | 16 +- v2/samples/notfound.json | 12 +- v2/samples/notfound.xml | 6 +- v2/samples/overlimit.xml | 8 +- v2/samples/server-fault.xml | 23 +- v2/samples/server-post-req-pip.json | 14 +- v2/samples/server-post-req-pip.xml | 5 +- v2/samples/server-post-req-pip2.json | 16 +- v2/samples/server-post-req-pip2.xml | 9 +- v2/samples/server-post-req-short.json | 2 +- v2/samples/server-post-req-short.xml | 31 +- v2/samples/server-post-req.json | 22 - v2/samples/server-post-req.xml | 24 - v2/samples/server-simple.json | 30 +- v2/samples/server-simple.xml | 17 +- v2/samples/version-atom.xml | 19 - v2/samples/version-get-resp.json | 33 + v2/samples/version-get-resp.xml | 14 + v2/samples/versions-atom.xml | 22 - v2/samples/versions-get-resp.json | 33 + v2/samples/versions-get-resp.xml | 16 + 30 files changed, 808 insertions(+), 1446 deletions(-) delete mode 100644 v2/samples/server-post-req.json delete mode 100644 v2/samples/server-post-req.xml delete mode 100644 v2/samples/version-atom.xml create mode 100644 v2/samples/version-get-resp.json create mode 100644 v2/samples/version-get-resp.xml delete mode 100644 v2/samples/versions-atom.xml create mode 100644 v2/samples/versions-get-resp.json create mode 100644 v2/samples/versions-get-resp.xml diff --git a/v2/bk_compute_api_ref_v2.xml b/v2/bk_compute_api_ref_v2.xml index e7db7ee..c1a76d8 100755 --- a/v2/bk_compute_api_ref_v2.xml +++ b/v2/bk_compute_api_ref_v2.xml @@ -25,14 +25,10 @@ '> ]> - + OpenStack Compute API v2 Reference Compute API Reference @@ -60,95 +56,87 @@ - Copyright details are filled in by the - template. + Copyright details are filled in by the template. - This document is intended for software developers - interested in developing applications using the - OpenStack Compute Application Programming Interface + This document is intended for software developers interested in developing + applications using the OpenStack Compute Application Programming Interface (API). - + 2014-08-01 + + Removes and replaces all WADL references with links to the OpenStack API Complete + Reference. + + + 2013-09-10 - Added the 422 return code to the - reboot server operation. + Added the 422 return code to the reboot server operation. - 2013-05-22 - Updated the book title for - consistency. + Updated the book title for consistency. - 2013-04-27 - Changed title of this book to - reflect that it contains Compute + Changed title of this book to reflect that it contains Compute extensions. - 2013-04-17 - Added the server admin actions - extension. + Added the server admin actions extension. - 2012-05-30 - Added more descriptive information - about the request body attributes to - the create server API - operation. + Added more descriptive information about the request body + attributes to the create server API operation. - 2012-05-02 - Added SHUTOFF to the - list of server status values for the - list servers API operation. + Added SHUTOFF to the list of server status values for + the list servers API operation. - Updated the description for the - SUSPENDED server - status value for the list servers API - operation. + Updated the description for the SUSPENDED server + status value for the list servers API operation. @@ -158,9 +146,8 @@ - Updated to use color-coded syntax - formatting in request and response - examples. + Updated to use color-coded syntax formatting in request and + response examples. @@ -170,9 +157,8 @@ - Added descriptions of URI parameters - and request body attributes for API - operations. + Added descriptions of URI parameters and request body attributes + for API operations. @@ -182,12 +168,10 @@ - Updated the API version from v1.1 to - v2. + Updated the API version from v1.1 to v2. - No longer use mimetype parameters to - denote version. + No longer use mimetype parameters to denote version. @@ -207,26 +191,22 @@ - Added limit - and marker - parameters to list operations. + Added limit and + marker parameters to list + operations. - The rebuild action behaves just like - create: an imageRef is used and a - password may be specified. + The rebuild action behaves the same as the create action: an + imageRef is used and a password can be specified. - Added tenant and user_id attributes - to server and image. + Added tenant and user_id attributes to server and image. - Added vcpus attribute to - flavors. + Added vcpus attribute to flavors. - The flavorRef attribute is now used - in the resize action. + The flavorRef attribute is now used in the resize action. @@ -236,79 +216,60 @@ - Added missing response examples for - server update. + Added missing response examples for server update. - Ensure consistent HTTP status codes - for all resources. + Ensure consistent HTTP status codes for all resources. - Clarifications on setting and - changing a server password. + Clarifications on setting and changing a server password. - Minor updates to metadata section - for clarity. + Minor updates to metadata section for clarity. Discuss alternate links. - Removed version number from compute - media types — use a media type - parameter instead. + Removed version number from compute media types — use a + media type parameter instead. - Bought back the flavorRef and - imageRef server attributes these are - now only used when creating a - server. + 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. + Made the create image operation a server action. - Added minDisk and minRam filters to - flavor lists. + Added minDisk and minRam filters to flavor lists. - Added minDisk and minRam attributes - to images. + Added minDisk and minRam attributes to images. - Asynchronous faults may now contain - a timestamp. + Asynchronous faults may now contain a time stamp. - Changes-since request returns an - empty list rather than a 304. + Changes-since request returns an empty list rather than a + 304. Added DELETED image status. - Fix content length in . + Fix content length in image create response sample. - Fixed bad request error code in - . + Fixed bad request error code in server passwords. - Compact image, server, and flavor - lists should contain IDs, names, and - links (Any kind of link may be - included — not just self + Compact image, server, and flavor lists should contain IDs, names, + and links (Any kind of link can be included — not just self links). - Changed metadata URI from .../meta - to .../metadata for + Changed metadata URI from .../meta to .../metadata for consistency. @@ -319,8 +280,7 @@ - Renamed Primary IP to Access - IP. + Renamed Primary IP to Access IP. @@ -330,32 +290,26 @@ - Many minor updates based on - community feedback. + Many minor updates based on community feedback. - Removed sections on Content - Compression, Persistent Connections, - and Caching — these are operator - specific. Added section on + 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. + A Location header is returned when creating servers/images. - Added filters to collection of - Image, Servers, and Flavors. + Added filters to collection of image, servers, and flavors. Added asynchronous faults. - Updates to links and references. - Remove serverRef, imageRef, and - flavorRef and instead embed one entity - in another to provide links. + Updates to links and references. Remove serverRef, imageRef, and + flavorRef and instead embed one entity in another to provide + links. Added primary IP addresses. @@ -364,38 +318,30 @@ Added forbidden fault. - We now use a single bookmark link - per entity regardless of + We now use a single bookmark link for each entity regardless of mimetype. - Collections are now sorted by create - time. + Collections are now sorted by create time. - Previous links are no longer - required. + Previous links are no longer required. - Added the ability to create or - update multiple metadata items + Added the ability to create or update multiple metadata items simultaneously. - Minor cleanups to server and image - state machine. + Minor cleanups to server and image state machine. - Update to JSON collection - format. + Update to JSON collection format. - Replace integer IDs with - UUIDs. + Replace integer IDs with UUIDs. - Removed affinityID, this will likely - come in as an extension. + Removed affinityID. @@ -405,8 +351,7 @@ - Some minor cleanups in preparation - for OpenStack Summit + Some minor cleanups in preparation for OpenStack Summit discussion. @@ -417,29 +362,23 @@ - Many minor updates based on - community feedback. + Many minor updates based on community feedback. - Updates to resource linking and - references. + Updates to resource linking and references. - Better description of paginated - collections. + Better description of paginated collections. - Metadata supported in servers and - images. + Metadata supported in servers and images. - Dropped support for shared IP - groups. + Dropped support for shared IP groups. - IPs organized by network ID, versus - showing only public and private - IPs. + IPs organized by network ID, versus showing only public and + private IPs. Generalized affinity ID. @@ -461,23 +400,18 @@ Preface - OpenStack Compute is a compute service that provides - server capacity in the cloud. Compute Servers come in - different flavors of memory, cores, disk space, and CPU, - and can be provisioned in minutes. Interactions with - Compute Servers can occur programmatically via the - OpenStack Compute API. + OpenStack Compute is a compute service that provides server capacity in the cloud. + Compute Servers come in different flavors of memory, cores, disk space, and CPU, and can + be provisioned in minutes. Interactions with Compute Servers can occur programmatically + via the OpenStack Compute API. We welcome feedback, comments, and bug reports at bugs.launchpad.net/nova. + xlink:href="http://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: + 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 @@ -489,136 +423,105 @@ HTTP/1.1 - JSON and/or XML data serialization - formats + JSON and/or XML data serialization formats
Document change history - This version of the Developer Guide replaces and - obsoletes all previous versions. The most recent - changes are described in the table below: + This version of the Developer Guide replaces and obsoletes all previous versions. + The most recent changes are described in the table below:
Additional resources - You can download the most current version of this - document from the OpenStack Docs website at + You can download the most current version of this document from the OpenStack Docs + website at http://docs.openstack.org.
General API 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. + 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.
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 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. + Each HTTP request against the OpenStack Compute system requires the inclusion of + specific authentication credentials. A single deployment may support multiple + authentication schemes (OAuth, Basic Auth, Token). The authentication scheme used is + determined by the provider of the OpenStack Compute system. Please contact your + provider to determine the best way to authenticate against this API. - Some authentication schemes may require that the - API operate using SSL over HTTP (HTTPS). + Some authentication schemes may require that the API operate using SSL over + HTTP (HTTPS).
-
+
Request and response formats - The OpenStack Compute API supports both JSON and XML - data serialization request and response - formats. + The OpenStack Compute API supports both JSON and XML data serialization 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: + 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: Content-Type: application/FORMAT - Where FORMAT is - either json or + Where FORMAT is either json or xml.
Response format - Use one of the following methods to specify the - response format: + Use one of the following methods to specify the response format: Accept header - The syntax for the - Accept header - is: + The syntax for the Accept header is: Accept: application/FORMAT - Where - FORMAT - is either json or - xml. The default - format is - json. + Where FORMAT is either + json or xml. The default + format is json. Query extension - Add an .xml or - .json extension - to the request URI. For example, the - .xml extension - in the following list servers URI - request specifies that the response - body is to be returned in XML - format: + Add an .xml or .json + extension to the request URI. For example, the + .xml extension in the following list servers + URI request specifies that the response body is to be returned in + XML format: &GET; publicURL/servers.xml - If you do not specify a response format, JSON is - the default. - If the Accept header and the query - extension specify conflicting formats, the format - specified in the query extension takes precedence. - For example, if the query extension is - .xml and the - Accept header specifies - application/json, the - response is returned in XML format. + If you do not specify a response format, JSON is the default. + If the Accept header and the query extension specify conflicting + formats, the format specified in the query extension takes precedence. For + example, if the query extension is .xml and the + Accept header specifies application/json, + the response is returned in XML format.
Request and response examples - You can serialize a response in a different - format from the request format. - and show a request body - in JSON format and a response body in XML format. - Though this document shows them, XML support in - requests and responses has been deprecated for the - Compute API v2 (stable) and v3 + You can serialize a response in a different format from the request + format. + and show + a request body in JSON format and a response body in XML format. + Though this document shows them, XML support in requests and responses + has been deprecated for the Compute API v2 (stable) and v3 (experimental). @@ -631,9 +534,8 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - shows - the headers and XML response returned by the JSON - request: + shows the headers and XML response + returned by the JSON request: XML response with headers HTTP/1.1 202 Accepted @@ -645,18 +547,14 @@ X-Compute-Request-Id: req-ab05045a-452f-4b46-be0d-86494da02a2b Server: Jetty(8.0.y.z-SNAPSHOT) - The following example shows an alternative - method of achieving the same result. The following - request uses an URI extension of - .xml instead of an - Accept header to request an XML - response. + The following example shows an alternative method of achieving the same + result. The following request uses an URI extension of .xml + instead of an Accept header to request an XML response. The XML response is not shown. - JSON request with XML query extension for - the response + JSON request with XML query extension for the response POST /v2/010101/servers.xml HTTP/1.1 Host: servers.api.openstack.org Content-Type: application/json @@ -668,13 +566,10 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
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. + 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. ID image reference: JSON request @@ -693,35 +588,27 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - 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: + 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 will be followed - immediately. + 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. + 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. + 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. - The type attribute provides a hint as to the - type of representation to expect when following - the link. + The type attribute provides a hint as to the type of representation to expect + when following the link. @@ -745,39 +632,29 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Paginated collections - To reduce load on the service, list operations will - return a maximum number of items at a time. The - maximum number of items returned is determined by the - compute provider. To navigate the collection, the - parameters limit and - marker can be set in the - URI. For example: + 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: ?limit=100&marker=1234 - The marker parameter is the - ID of the last item in the previous list. Items are - sorted by create time in descending order. When a - create time is not available they are sorted by ID. - The 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 will return a badRequest - (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 - contain a "next" link. The following examples - illustrate three pages in a collection of images. The - first page was retrieved via a &GET; to - http://servers.api.openstack.org/v2/1234/images?limit=1. - In these examples, the limit - parameter sets the page size to a single item. - Subsequent links will honor the initial page size. - Thus, a client may follow links to traverse a - paginated collection without having to input the + The marker parameter is the ID of the last item in the + previous list. Items are sorted by create time in descending order. When a create + time is not available they are sorted by ID. The 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 are required to contain atom next + links. They may optionally also 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/images?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. - Images collection: XML (first page) @@ -805,23 +682,17 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb Images collection: JSON (last page) - 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. + 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. Paginated image metadata: XML @@ -834,77 +705,52 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
- Efficient polling with the - <parameter>Changes-Since</parameter> - 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 will be assumed. - If nothing has changed since the - changes-since time, an - empty list will be returned. If data has changed, only - the items changed since the specified time will be - returned in the response. For example, performing a - &GET; against + Efficient polling with the <parameter>Changes-Since</parameter> 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=2011-01-24T17:08Z - would list all servers that have changed since Mon, 24 - 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 - 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 + would list all servers that have changed since Mon, 24 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 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.
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 or see . Your provider may - be able to adjust your account's limits if they are - too low. + 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 or see . Your provider may be able to adjust your + account's limits if they are too low.
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. + 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. @@ -954,30 +800,24 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Sample rate limits
- 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 will - be returned with a Retry-After header - to notify the client when they can attempt to try - again. + 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. + 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. - + @@ -994,27 +834,23 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - + - + - + - +
Sample Absolute LimitsSample absolute limits
Name
maxServerMeta 5Maximum number of metadata items - associated with a serverMaximum number of metadata items associated with a server
maxImageMeta 5Maximum number of metadata items - associated with an ImageMaximum number of metadata items associated with an Image
maxPersonality 5The maximum number of file - path/content pairs that can be - supplied on server buildThe maximum number of file path/content pairs that can be supplied + on server build
maxPersonalitySize 10240The maximum size, in bytes, for each - personality fileThe maximum size, in bytes, for each personality file
@@ -1022,33 +858,23 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Determine limits programmatically - Applications can programmatically determine - current account limits using the /limits URI as - follows: - - - - - + Applications can programmatically determine current account limits. For + information, see Limits.
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/ - v1.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. + The OpenStack Compute API uses both a URI and a MIME type versioning scheme. In + the URI scheme, the first element of the path contains the target version identifier + (e.g. https://servers.api.openstack.org/ v1.0/…). The MIME type versioning + scheme uses HTTP content negotiation where the 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. Request with MIME type versioning @@ -1068,17 +894,14 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - The MIME type versioning approach allows for the - creating of permanent links, because the version - scheme is not specified in the URI path: + 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) will follow - providing links and MIME types to available - versions. + 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. Multiple choices: XML response @@ -1089,167 +912,69 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - New features and functionality that do not break - API-compatibility will be introduced in the current - version of the API as extensions (see below) and the - URI and MIME types will remain unchanged. Features or - functionality changes that would necessitate a break - in API-compatibility will require a new version, which - will result in URI and MIME type version being updated - accordingly. When new API versions are released, older - versions will be marked as 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. Note that an Atom - representation of the versions resources is supported - 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. - - List versions: request - GET HTTP/1.1 -Host: servers.api.openstack.org - - Normal Response Code(s): - 200, - 203 - - Error Response Code(s): - 400, - 413, - 500, - 503 - - This operation does not require a request - body. - - List versions: XML response - - - - - List versions: Atom response - - - - List versions: JSON response - - - - 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 should always end with a trailing slash - (/). If the slash is omitted, the server may respond - with a 302 redirection - request. Format extensions may be placed after the - slash (e.g. - https://servers.api.openstack.org/v2/.xml). Note that - this is a special case that does not hold true for - other API requests. In general, requests such as - /servers.xml and /servers/.xml are handled - equivalently. - - Get version details: request - GET HTTP/1.1 -Host: servers.api.openstack.org/v2/ - - Normal Response Code(s): - 200, - 203 - - Error Response Code(s): computeFault - (400, - 500, …), - serviceUnavailable (503), - unauthorized (401), forbidden - (403), badRequest - (400), badMethod - (405), overLimit - (413) - This operation does not require a request - body - - Get version details: XML response - - - - - Get version details: Atom response - - - - - Get version details: JSON response - - - 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). + New features and functionality that do not break API-compatibility are introduced + in the current version of the API as extensions (see the following section) 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/.xml). - 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. + This special case does not hold true for other API requests. In general, + requests such as /servers.xml and + /servers/.xml 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). + + 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.
Extensions - The OpenStack Compute API is extensible. Extensions - serve two purposes: They allow the introduction of new - features in the API without requiring a version change - and they allow the introduction of vendor specific - niche functionality. Applications can programmatically - 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 + The OpenStack Compute API is extensible. Extensions serve two purposes: They allow + the introduction of new features in the API without requiring a version change and + they allow the introduction of vendor specific niche functionality. Applications can + programmatically 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 as an - unavailable extension will issue an itemNotFound - (404) response. - Extensions may define new data types, parameters, - actions, headers, states, and resources. In XML, - additional elements and attributes may be defined. - These elements must be defined in the extension's - namespace. In JSON, the alias must be used. The - volumes element in the and is defined in the RS-CBS namespace. - Actions work in exactly the same manner as illustrated - in and . - 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 may be in - the RS-PIE:PrepareShare state. + 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. - Applications should be prepared to 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. + 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. Extended server: XML response @@ -1267,25 +992,14 @@ Host: servers.api.openstack.org/v2/ Extended action: JSON response -
Faults
Synchronous faults - When an error occurs at request time, the system - will return an HTTP error response code denoting - the type of error. The system will also return - additional information about the fault in the body - of the response. + When an error occurs at request time, the system also returns additional + information about the fault in the body of the response. Fault: XML response @@ -1294,28 +1008,23 @@ Host: servers.api.openstack.org/v2/ Fault: JSON response - The error code is returned in the body of the - response for convenience. The message section - returns a human-readable message that is - appropriate for display to the end user. The - details section is optional and may contain - information—for example, a stack - trace—to assist in tracking down an error. - The detail section may or may not be appropriate - for display to an end user. - The root element of the fault (e.g. - computeFault) may change depending on the type of - error. The following is a list of possible - elements along with their associated error - codes. + 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. - + - - - + + + @@ -1405,20 +1114,15 @@ Host: servers.api.openstack.org/v2/Item Not Found fault: XML response - From an XML schema perspective, all API faults - are extensions of the base fault type - ComputeAPIFault. When working with a system that - binds XML to actual classes (such as JAXB), one - should be capable of using ComputeAPIFault as a - “catch-all” if there's no interest in - distinguishing between individual fault + 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. + 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. Over Limit fault: XML response @@ -1430,17 +1134,13 @@ Host: servers.api.openstack.org/v2/
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 + 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. @@ -1449,8 +1149,7 @@ Host: servers.api.openstack.org/v2/ - Server in error state: JSON - response + Server in error state: JSON response @@ -1465,556 +1164,250 @@ Host: servers.api.openstack.org/v2/
- - - API operations
- Servers + Server concepts
- List servers - 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 + 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. + ACTIVE. The server is active. - BUILD. The server has not - finished the original build + BUILD. The server has not finished the original build process. - DELETED. The server is - deleted. + DELETED. The server is deleted. - ERROR. The server is in - error. + 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. + 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. + 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. + 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 + REBUILD. The server is currently being rebuilt from an image. - RESCUE. The server is in - rescue mode. + 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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. - HostId is unique - per account and is - not globally unique. + HostId is unique per account and + is not globally unique. - - - - - -
-
- Create server + Server creation
+ BUILD &ARROW; ERROR (on error) - This operation asynchronously provisions a new - server. The progress of this operation depends on - several factors including location of the - requested image, network i/o, host load, and the - selected flavor. The progress of the request can - be checked by performing a &GET; on - /servers/id, which will - return a progress attribute (0-100% completion). - The full URL to the newly created server is - returned via the Location header and - is available as a self and - bookmark link in the server - representation (See ). Note that when - creating a server only the server ID, its links, - and the admin password are guaranteed to be - returned in the request. Additional attributes may - be retrieved by performing subsequent &GET;s on - the server. - - - - - -
- Server passwords - A password may be specified when creating - the server via the optional - adminPass attribute. - The specified password must meet the - complexity requirements set by your OpenStack - Compute provider. The server may enter an - ERROR state if the complexity - requirements are not met. In this case, a - client may issue a change password action to - reset the server password. - If a password is not specified, a randomly - generated password will be assigned and - returned in the response object. This password - is guaranteed to meet the security - requirements set by the compute provider. For - security reasons, the password will not be - returned in subsequent &GET; calls. -
-
- Server metadata - Custom server metadata can also be supplied - at launch time. See for details on - working with metadata. The maximum size of the - metadata key and value is 255 bytes each. The - maximum number of key-value pairs that can be - supplied per server is determined by the - compute provider and may be queried via the - maxServerMeta absolute limit. -
-
- Server networks - Networks which the server connects to can - also be supplied at launch time. See for details on - working with networks. 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 - - 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 file /etc/passwd - 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 ( ). -
-
- Server access addresses - In a hybrid environment, the IP address of a - server may not be controlled by the underlying - implementation. Instead, the access IP address - may be part of the dedicated hardware; for - example, a router/NAT device. In this case, - the addresses provided by the implementation - cannot actually be used to access the server - (from outside the local LAN). Here, a separate - 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. See . - Nonetheless, clients which need to access the - server directly are encouraged to do so via an - access address. In the example below, an IPv4 - address is assigned at creation time. - - Create server with access IP: XML - request - - - - Create server with access IP: JSON - request - - - - Both IPv4 and IPv6 addresses may be used - as access addresses and both addresses may - be assigned simultaneously as illustrated - below. Access addresses may be updated - after a server has been created. See for more - details. - - - Create server with multiple access IPs: - XML request - - - - - Create server with multiple access IPs: - JSON request - - -
+ 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 (See ). 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. -
- Get server details - - - - - +
+ 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.
- -
- Update server - - - - - +
+ 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.
- -
- Delete server - - - - - +
+ 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 + + 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 ( ). +
+
+ 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. + + Create server with access IP: XML request + + + + Create server with access IP: JSON request + + + + Both IPv4 and IPv6 addresses may be used as access addresses and both + addresses may be assigned simultaneously as illustrated below. Access + addresses may be updated after a server has been created. See for more details. + + + Create server with multiple access IPs: XML request + + + + + Create server with multiple access IPs: JSON request + +
-
- -
- Server addresses - Lists addresses for a specified server or a - specified server and network. - - - - -
- -
- Server actions - - - -
- -
- Flavors - A flavor is an available hardware configuration for - a server. Each flavor has a unique combination of disk - space and memory capacity. - - - - -
- -
- Images - An image is a collection of files you use to create - or rebuild a server. Operators provide pre-built OS - images by default. You may also create custom - images. - - - - -
- -
- Metadata - The following operations enable access to metadata - after a server or image has been created. - - - - - - -
- -
- Networks - Using the network API you can create, update, delete - and show networks, ports and subnets. A few examples - are given below. -
Fault Elements and Error CodesFault elements and error codes
Fault ElementAssociated Error CodesExpected in All RequestsFault elementAssociated error codesExpected in all requests?
Status Transition: - BUILD &ARROW; - ACTIVE + BUILD &ARROW; ACTIVE
- BUILD &ARROW; - ERROR (on error)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Get all networks
MethodURIDescription
GET/v2.0/networksReturns an array of all networks
GET/v2.0/networks/{network_id}Return network with given id
POST/v2.0/networksCreates new network
DELETE/v2.0/networks/{network_id}Delete network with given id
- You can specify the following attributes for a - network. - - - - - - - - - - - - - - - - - - - - - - - - - - -
Network attributes
NameTypeDescription
uuiduuidThe uuid of the network.
fixed_ipIPv4The IP address to assign to the - interface.
portuuidThe uuid of the port.
- - The fixed_ip parameter is - used only when network uuid - is specified; also, when - port is specified, - network uuid and - fixed_ip are properties - of the port and are ignored. Omit - fixed_ip and (network) - uuid to avoid - validation errors. -
- + + API operations and extensions + For information about Compute API operations, see Compute API v2 (CURRENT). + For information about Compute API extensions, see Compute API v2 extensions (CURRENT). + diff --git a/v2/pom.xml b/v2/pom.xml index d378b80..9b6beaf 100644 --- a/v2/pom.xml +++ b/v2/pom.xml @@ -69,34 +69,34 @@ + dir="${basedir}/target/docbkx/webhelp/api/openstack-compute/v2/"/> + todir="${basedir}/target/docbkx/webhelp/api/openstack-compute/v2/xsd"> + todir="${basedir}/target/docbkx/webhelp/api/openstack-compute/v2/xslt"> + todir="${basedir}/target/docbkx/webhelp/api/openstack-compute/v2/style"> + todir="${basedir}/target/docbkx/webhelp/api/openstack-compute/v2/js"> + todir="${basedir}/target/docbkx/webhelp/api/openstack-compute/v2/samples"> @@ -104,7 +104,7 @@ + todir="${basedir}/target/docbkx/webhelp/api/openstack-compute/v2/"> diff --git a/v2/samples/choices.json b/v2/samples/choices.json index 9ce8a4b..ab3faca 100644 --- a/v2/samples/choices.json +++ b/v2/samples/choices.json @@ -1,44 +1,44 @@ { - "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" - } - ] - } - ] -} + "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" + } + ] + } + ] +} \ No newline at end of file diff --git a/v2/samples/fault.json b/v2/samples/fault.json index 157a208..c806199 100644 --- a/v2/samples/fault.json +++ b/v2/samples/fault.json @@ -1,7 +1,7 @@ { - "computeFault" : { - "code" : 500, - "message" : "Fault!", - "details" : "Error Details..." - } -} + "computeFault":{ + "code":500, + "message":"Fault!", + "details":"Error Details..." + } +} \ No newline at end of file diff --git a/v2/samples/image-fault.xml b/v2/samples/image-fault.xml index 6d320db..695fb2a 100644 --- a/v2/samples/image-fault.xml +++ b/v2/samples/image-fault.xml @@ -1,20 +1,14 @@ - - + An internal error occurred
Error details
 - - - + \ No newline at end of file diff --git a/v2/samples/image-meta-page1.xml b/v2/samples/image-meta-page1.xml index 085cf3a..67412c2 100644 --- a/v2/samples/image-meta-page1.xml +++ b/v2/samples/image-meta-page1.xml @@ -1,17 +1,14 @@ - + 1.5 Gold - - - + + \ No newline at end of file diff --git a/v2/samples/image-simple.xml b/v2/samples/image-simple.xml index a187665..a0281db 100644 --- a/v2/samples/image-simple.xml +++ b/v2/samples/image-simple.xml @@ -1,16 +1,10 @@ - - + - - - + \ No newline at end of file diff --git a/v2/samples/images-page1.xml b/v2/samples/images-page1.xml index d7e5481..7cdad27 100644 --- a/v2/samples/images-page1.xml +++ b/v2/samples/images-page1.xml @@ -1,6 +1,5 @@ - + - + \ No newline at end of file diff --git a/v2/samples/images-page2.xml b/v2/samples/images-page2.xml index c1cfc1f..e3a571d 100644 --- a/v2/samples/images-page2.xml +++ b/v2/samples/images-page2.xml @@ -1,11 +1,10 @@ - + - + + href="http://servers.api.openstack.org/v2/1234/images?limit=1&marker=52415800-8b69-11e0-9b19-734f5736d2a2" + /> + \ No newline at end of file diff --git a/v2/samples/images-page3.xml b/v2/samples/images-page3.xml index 831a2e2..52146be 100644 --- a/v2/samples/images-page3.xml +++ b/v2/samples/images-page3.xml @@ -1,10 +1,8 @@ - - - - - + + + + + \ No newline at end of file diff --git a/v2/samples/notfound.json b/v2/samples/notfound.json index 8c99856..0e16609 100644 --- a/v2/samples/notfound.json +++ b/v2/samples/notfound.json @@ -1,7 +1,7 @@ { - "itemNotFound" : { - "code" : 404, - "message" : "Not Found", - "details" : "Error Details..." - } -} + "itemNotFound":{ + "code":404, + "message":"Not Found", + "details":"Error Details..." + } +} \ No newline at end of file diff --git a/v2/samples/notfound.xml b/v2/samples/notfound.xml index ecfe242..16cb487 100644 --- a/v2/samples/notfound.xml +++ b/v2/samples/notfound.xml @@ -1,7 +1,5 @@ - + Not Found
Error Details...
- + \ No newline at end of file diff --git a/v2/samples/overlimit.xml b/v2/samples/overlimit.xml index 8dbcc5b..6a015cc 100644 --- a/v2/samples/overlimit.xml +++ b/v2/samples/overlimit.xml @@ -1,8 +1,6 @@ - + OverLimit Retry...
Error Details...
- + \ No newline at end of file diff --git a/v2/samples/server-fault.xml b/v2/samples/server-fault.xml index 5cd3929..5e66b5d 100644 --- a/v2/samples/server-fault.xml +++ b/v2/samples/server-fault.xml @@ -1,21 +1,16 @@ - - - + + + Could not find image 52415800-8b69-11e0-9b19-734f6f007777
Fault details
 - - - + \ No newline at end of file diff --git a/v2/samples/server-post-req-pip.json b/v2/samples/server-post-req-pip.json index 890840c..d2a96bf 100644 --- a/v2/samples/server-post-req-pip.json +++ b/v2/samples/server-post-req-pip.json @@ -1,8 +1,8 @@ { - "server" : { - "name" : "new-server-test", - "imageRef" : "52415800-8b69-11e0-9b19-734f6f006e54", - "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37", - "accessIPv4" : "67.23.10.132" - } -} + "server":{ + "name":"new-server-test", + "imageRef":"52415800-8b69-11e0-9b19-734f6f006e54", + "flavorRef":"52415800-8b69-11e0-9b19-734f1195ff37", + "accessIPv4":"67.23.10.132" + } +} \ No newline at end of file diff --git a/v2/samples/server-post-req-pip.xml b/v2/samples/server-post-req-pip.xml index 668408a..2f1fec8 100644 --- a/v2/samples/server-post-req-pip.xml +++ b/v2/samples/server-post-req-pip.xml @@ -1,5 +1,4 @@ - + flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"/> \ No newline at end of file diff --git a/v2/samples/server-post-req-pip2.json b/v2/samples/server-post-req-pip2.json index 0120891..2931443 100644 --- a/v2/samples/server-post-req-pip2.json +++ b/v2/samples/server-post-req-pip2.json @@ -1,9 +1,9 @@ { - "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" - } -} + "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" + } +} \ No newline at end of file diff --git a/v2/samples/server-post-req-pip2.xml b/v2/samples/server-post-req-pip2.xml index 8a04a90..a471691 100644 --- a/v2/samples/server-post-req-pip2.xml +++ b/v2/samples/server-post-req-pip2.xml @@ -1,7 +1,4 @@ - + \ No newline at end of file diff --git a/v2/samples/server-post-req-short.json b/v2/samples/server-post-req-short.json index b725c57..3076047 100644 --- a/v2/samples/server-post-req-short.json +++ b/v2/samples/server-post-req-short.json @@ -13,4 +13,4 @@ } ] } -} +} \ No newline at end of file diff --git a/v2/samples/server-post-req-short.xml b/v2/samples/server-post-req-short.xml index ac19dcc..aed82a0 100644 --- a/v2/samples/server-post-req-short.xml +++ b/v2/samples/server-post-req-short.xml @@ -1,24 +1,19 @@ - + Apache1 - - ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp - dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k - IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs - c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g - QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo - ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv - dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy - c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 - b25zLiINCg0KLVJpY2hhcmQgQmFjaA== - + ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp + dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k + IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs + c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g + QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo + ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv + dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy + c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 + b25zLiINCg0KLVJpY2hhcmQgQmFjaA== - + \ No newline at end of file diff --git a/v2/samples/server-post-req.json b/v2/samples/server-post-req.json deleted file mode 100644 index 36c02c6..0000000 --- a/v2/samples/server-post-req.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "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" - } - ], - "networks":[ - { - "uuid":"c6a48469-4638-4346-b755-6e66ed7abdff", - "fixed_ip":"10.0.0.10" - } - ] - } -} \ No newline at end of file diff --git a/v2/samples/server-post-req.xml b/v2/samples/server-post-req.xml deleted file mode 100644 index 6abbe8f..0000000 --- a/v2/samples/server-post-req.xml +++ /dev/null @@ -1,24 +0,0 @@ - - - - Apache1 - - - - ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp - dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k - IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs - c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g - QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo - ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv - dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy - c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 - b25zLiINCg0KLVJpY2hhcmQgQmFjaA== - - - - - diff --git a/v2/samples/server-simple.json b/v2/samples/server-simple.json index 4796515..362df16 100644 --- a/v2/samples/server-simple.json +++ b/v2/samples/server-simple.json @@ -1,16 +1,16 @@ { - "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" - } - ] - } -} + "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" + } + ] + } +} \ No newline at end of file diff --git a/v2/samples/server-simple.xml b/v2/samples/server-simple.xml index 336ca14..265fb8f 100644 --- a/v2/samples/server-simple.xml +++ b/v2/samples/server-simple.xml @@ -1,11 +1,8 @@ - - - - + + + + \ No newline at end of file diff --git a/v2/samples/version-atom.xml b/v2/samples/version-atom.xml deleted file mode 100644 index c168106..0000000 --- a/v2/samples/version-atom.xml +++ /dev/null @@ -1,19 +0,0 @@ - - - About This Version - 2011-01-21T11:33:21-06:00 - http://servers.api.openstack.org/v1.0/ - Rackspacehttp://www.rackspace.com/ - - - http://servers.api.openstack.org/v1.0/ - Version v2 - 2011-01-21T11:33:21-06:00 - - - - Version v2 CURRENT (2011-01-21T11:33:21-06:00) - - diff --git a/v2/samples/version-get-resp.json b/v2/samples/version-get-resp.json new file mode 100644 index 0000000..f3ab363 --- /dev/null +++ b/v2/samples/version-get-resp.json @@ -0,0 +1,33 @@ +{ + "version":{ + "status":"CURRENT", + "updated":"2011-01-21T11:33:21Z", + "media-types":[ + { + "base":"application/xml", + "type":"application/vnd.openstack.compute+xml;version=2" + }, + { + "base":"application/json", + "type":"application/vnd.openstack.compute+json;version=2" + } + ], + "id":"v2.0", + "links":[ + { + "href":"http://23.253.228.211:8774/v2/", + "rel":"self" + }, + { + "href":"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", + "type":"application/pdf", + "rel":"describedby" + }, + { + "href":"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + "type":"application/vnd.sun.wadl+xml", + "rel":"describedby" + } + ] + } +} \ No newline at end of file diff --git a/v2/samples/version-get-resp.xml b/v2/samples/version-get-resp.xml new file mode 100644 index 0000000..3a47e3d --- /dev/null +++ b/v2/samples/version-get-resp.xml @@ -0,0 +1,14 @@ + + + + + + + + + + \ No newline at end of file diff --git a/v2/samples/versions-atom.xml b/v2/samples/versions-atom.xml deleted file mode 100644 index ef701c9..0000000 --- a/v2/samples/versions-atom.xml +++ /dev/null @@ -1,22 +0,0 @@ - - - Available API Versions - 2010-12-12T18:30:02.25Z - http://servers.api.openstack.org/ - Rackspacehttp://www.rackspace.com/ - - - http://servers.api.openstack.org/v2/ - Version v2 - 2010-12-12T18:30:02.25Z - - Version v2 CURRENT (2010-12-12T18:30:02.25Z) - - - http://servers.api.openstack.org/v1.0/ - Version v1.0 - 2009-10-09T11:30:00Z - - Version v1.0 DEPRECATED (2009-10-09T11:30:00Z) - - diff --git a/v2/samples/versions-get-resp.json b/v2/samples/versions-get-resp.json new file mode 100644 index 0000000..5499236 --- /dev/null +++ b/v2/samples/versions-get-resp.json @@ -0,0 +1,33 @@ +{ + "version": { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "media-types": [ + { + "base": "application/xml", + "type": "application/vnd.openstack.compute+xml;version=2" + }, + { + "base": "application/json", + "type": "application/vnd.openstack.compute+json;version=2" + } + ], + "id": "v2.0", + "links": [ + { + "href": "http://23.253.228.211:8774/v2/", + "rel": "self" + }, + { + "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", + "type": "application/pdf", + "rel": "describedby" + }, + { + "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", + "type": "application/vnd.sun.wadl+xml", + "rel": "describedby" + } + ] + } +} \ No newline at end of file diff --git a/v2/samples/versions-get-resp.xml b/v2/samples/versions-get-resp.xml new file mode 100644 index 0000000..855a873 --- /dev/null +++ b/v2/samples/versions-get-resp.xml @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + +