From f566433a8e3dc6d5fa3ce9b54e958aedf0520a44 Mon Sep 17 00:00:00 2001 From: Diane Fleming Date: Mon, 26 Mar 2012 13:45:07 -0500 Subject: [PATCH] Added descriptions of URI parameters and request body attributes to all API operations. Patch set #2 removes the *.bak file. Patch set #3 adds link to PDF. Patch set #4 removed xmlns descriptions Patch set #5 revised description of imageRef and flavorRef Change-Id: Ic84cf690f5599e488aaec77166ec16b0fb1ac094 --- .../src/os-compute-devguide.xml | 1895 +++++++++++------ .../src/samples/server-put-resp.json | 2 +- 2 files changed, 1272 insertions(+), 625 deletions(-) diff --git a/openstack-compute-api-2/src/os-compute-devguide.xml b/openstack-compute-api-2/src/os-compute-devguide.xml index 57f0db9..becd293 100644 --- a/openstack-compute-api-2/src/os-compute-devguide.xml +++ b/openstack-compute-api-2/src/os-compute-devguide.xml @@ -44,6 +44,7 @@ version="5.0" xml:id="os-cs-devguide"> OpenStack Compute Developer Guide + OpenStack Compute Dev Guide @@ -76,7 +77,20 @@ (API). - + + + 2012-03-25 + + + + Added descriptions of URI parameters + and request body attributes for API + operations. + + + + + 2012-02-14 @@ -468,12 +482,16 @@ xlink:href="http://bugs.launchpad.net/nova">bugs.launchpad.net/nova.
Intended Audience - This Guide is intended to assist software developers who want to develop - applications using the OpenStack Compute API. To use the information provided here, - you should first have a general understanding of the OpenStack Compute service and - have access to an account from an OpenStack Compute provider. You should also be - familiar with: + This guide is intended to assist software developers + who want to develop applications using the OpenStack + Compute API. To use this information, you should have + access to an account from an OpenStack Compute + provider, and you should also be familiar with the + following concepts: + + OpenStack Compute service + ReSTful web services @@ -481,7 +499,8 @@ HTTP/1.1 - JSON and/or XML data serialization formats + JSON and/or XML data serialization + formats
@@ -501,14 +520,17 @@ website at http://docs.openstack.org. - For more details about the Cloud Servers service that this API is based upon, please refer to http://www.rackspacecloud.com/cloud_hosting_products/servers. Related - documents, including an API Language Binding Guide, are available at the same site, as are links - to Rackspace's official support channels, including knowledge base articles, forums, - phone, chat, and email. + For more details about the Cloud Servers service + that this API is based upon, see http://www.rackspacecloud.com/cloud_hosting_products/servers. + This site also provides related documents and links to + official support channels for Rackspace, including + knowledge base articles, forums, phone, chat, and email. @@ -910,7 +932,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb would list all servers that have changed since Mon, 24 Jan 2011 17:08:00 UTC. - In order to allow clients to keep track of changes, + 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 @@ -1669,28 +1691,28 @@ Host: servers.api.openstack.org/v2/ - Server In Error Sate: XML + Server In Error State: XML - Server In Error Sate: JSON + Server In Error State: JSON - Image In Error Sate: XML + Image In Error State: XML - Image In Error Sate: JSON + Image In Error State: JSON @@ -1722,7 +1744,8 @@ Host: servers.api.openstack.org/v2/ marker=markerID&limit=int& changes-since=dateTime - List all servers (IDs, names, links) + Lists IDs, names, and + links for all servers. &GET; @@ -1733,24 +1756,24 @@ Host: servers.api.openstack.org/v2/ marker=markerID&limit=int& changes-since=dateTime - List all servers (all details) + Lists all details for all + servers. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413) Office Annotation @@ -1761,67 +1784,156 @@ Host: servers.api.openstack.org/v2/ 2009-06-26T14:30:46 - - Well need to revisit. List all status even + Well need to revisit. List all status even the ones that don't enter into our state - transitions along with descriptions of each. - + transitions along with descriptions of each. - - This operation provides a list of servers - associated with your account. Servers that have - been deleted are not included in this list. - Servers contain a status attribute that can be - used as an indication of the current server state. - Servers with an ACTIVE status are - available for use. Other possible values for the - status attribute include: BUILD, - REBUILD, SUSPENDED, - RESIZE, VERIFY_RESIZE, - REVERT_RESIZE, - PASSWORD, REBOOT, - HARD_REBOOT, DELETED, - UNKNOWN, and ERROR. - - - The list of servers may be filtered by image, - flavor, name, and status via the respective query - parameters. Image and flavor references may be IDs - or full URLs. When retrieving a list of servers - via the changes-since parameter, the list will - contain servers that have been deleted since the - changes-since time (see ). - - - The compute provisioning algorithm has an - anti-affinity property that attempts to spread out - customer VMs across hosts. Under certain - situations, VMs from the same customer may be + You can filter the list of + servers by image, flavor, name, and status through + the respective query parameters. + To filter the list of servers returned in the + response body, specify one or more of the + following optional parameters in the request URI: + + image + + The image reference specified as + an ID or full URL. + + + + flavor + + The flavor reference specified + as an ID or full URL. + + + + server + + The server name. + + + + status + + The server status, which is one + of the following values: + + ACTIVE + + + BUILD + + + DELETED + + + ERROR + + + HARD_REBOOT + + + PASSWORD + + + REBOOT + + + REBUILD + + + RESIZE + + + SUSPENDED + + + UNKNOWN + + + VERIFY_RESIZE + + + + + + marker + + The ID of the last item in the + previous list. See . + + + + limit + + The page size. See . + + + + changes-since + + The changes-since time. The list + contains servers that have been + deleted since the changes-since + time. See . + + + + This operation does not require a request + body. + This operation lists the servers associated with + your account. The list does not include servers + that have been deleted. Servers contain a status + attribute that can be used as an indication of the + current server state. Servers with an + ACTIVE status are available for + use. Other possible values for the status + attribute include: BUILD, + REBUILD, SUSPENDED, + RESIZE, + VERIFY_RESIZE, + PASSWORD, REBOOT, + HARD_REBOOT, + DELETED, UNKNOWN, and + ERROR. + 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's relevant to your - application. - + 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. - This operation does not require a request body. - + + + + The following examples show an XML and JSON + response for the list servers API + operation: + - Servers List Response: XML (detail) + List Servers Response: XML (detail) - + - Servers List Response: JSON (detail) + List Servers Response: JSON + (detail) @@ -1842,27 +1954,26 @@ Host: servers.api.openstack.org/v2/ &POST; /servers - Create a new server + Creates a new server. - - Normal Response Code(s): - 202 + Normal Response Code(s): + 202 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - serverCapacityUnavailable (503) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), + serverCapacityUnavailable + (503) @@ -1879,26 +1990,81 @@ Host: servers.api.openstack.org/v2/ - - This operation asynchronously provisions a new + 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 + /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 + bookmark link in the server representation (See ). Note that when + linkend="LinksReferences"/>). Note that when creating a server only the server ID, its links, and the admin password are guaranteed to be - returned in the request. Additional - attributes may be retrieved by performing - subsequent &GET;s on the server. + returned in the request. Additional attributes may + be retrieved by performing subsequent &GET;s on + the server. + The following table + describes the required and optional attributes + that you can specify in the request body: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Create Server Request + Attributes
NameDescriptionRequired
imageRefThe image reference. Specify as an ID or full URL. Yes
flavorRefThe flavor reference. Specify as an ID or full URL. Yes
+ name + + The server name. + Yes
+ metadata + Metadata key and value pairs.No
+ personality + + File path and + contents. + No
 Server Create Request: XML @@ -2085,36 +2251,37 @@ Host: servers.api.openstack.org/v2/ &GET; /servers/id - List details of the specified server + Lists details of the + specified server. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404) - - - This operation returns the details of a specific - server by its ID. - - This operation does not require a request body. + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404) + Specify the server ID as + id in the URI. + This operation does not require a request + body. + This operation returns the details of a specific + server by its ID. Server Details Response: XML - + Server Details Response: JSON @@ -2135,28 +2302,27 @@ Host: servers.api.openstack.org/v2/ &PUT; /servers/id - Update the specified - server's editable attributes + Updates the editable + attributes for the specified + server. - - Normal Response Code(s): - 200 + Normal Response Code(s): + 200 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), buildInProgress + (409) @@ -2168,10 +2334,51 @@ Host: servers.api.openstack.org/v2/ - This operation updates the editable attributes of a server: the name of the - server and the IPv4 and IPv6 access addresses. Note that while the server name - is editable, the operation does not change the server host name. Note also that - server names are not guaranteed to be unique. + This operation enables you to update the + editable attributes of a specified server. + Specify the server ID as + id in the URI. + The following table describes the attributes + that you can specify in the request body: + + + + + + + + + + + + + + + + + + + + + + + +
Update Server Request Body + Attributes
AttributeDescription
nameThe name of the server. If you + edit the server name, the server + host name does not change. Also, + server names are not guaranteed to + be unique.
+ accessIPv4 + + The IP version 4 address. +
+ accessIPv6 + + The IP version 6 + address. +
Server Update Name Request: XML @@ -2245,7 +2452,8 @@ Host: servers.api.openstack.org/v2/ &DELETE; /servers/id - Terminate the specified server + Deletes the specified + server. @@ -2283,7 +2491,12 @@ Host: servers.api.openstack.org/v2/ - This operation deletes a cloud server instance from the system. It does not require a request or a response body. + This operation deletes a specified cloud server + instance from the system. + Specify the ID for the cloud server instance as + id in the URI. + This operation does not require a request body + or return a response body. @@ -2303,27 +2516,32 @@ Host: servers.api.openstack.org/v2/ &GET; /servers/id/ips - List all server addresses + Lists all networks and + addresses associated with a specified + server. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - buildInProgress (409) - - This operation does not require a request body. + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), buildInProgress + (409) + This operation lists all networks and addresses + associated with a specified server. + Specify the server ID as + id in the URI. + This operation does not require a request body. Addresses List Response: XML @@ -2352,7 +2570,9 @@ Host: servers.api.openstack.org/v2/ &GET; /servers/id/ips/networkID - List addresses by Network ID + Lists addresses associated + with a specified server and + network. @@ -2372,15 +2592,50 @@ Host: servers.api.openstack.org/v2/ itemNotFound (404), buildInProgress (409) - This operation does not require a request body. + This operation lists all addresses associated + with a specified server and network. + The following table describes the required + parameters that you specify in the request URI: + + + + + + + + + + + + + + + + + + + + +
List Addresses by Network URI + Parameters
NameDescription
+ id + + The server ID. +
+ networkID + + The network ID. +
This operation does not require a request body. - List Addresses by Network: XML + List Addresses by Network Response: + XML - List Addresses by Network: JSON + List Addresses by Network Response: + JSON @@ -2391,7 +2646,7 @@ Host: servers.api.openstack.org/v2/
Server Actions
- Change Password + Change Administrator Password @@ -2404,27 +2659,26 @@ Host: servers.api.openstack.org/v2/ &POST; /servers/id/action - Change a server's password + Changes the administrator + password for a specified server. - - Normal Response Code(s): - 202 + Normal Response Code(s): + 202 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), buildInProgress + (409) @@ -2454,28 +2708,54 @@ Host: servers.api.openstack.org/v2/ - - This operation changes the server's administrator - password. The specified password must meet the - complexity requirements set by your OpenStack - Compute provider. The server may enter an - ERROR state if the complexity - requirements are not met. In this case, a client - may reissue the change password action. - + This operation changes the administrator + password for a specified server. + Specify the server ID as + id in the URI. + 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 + may reissue the change password action. + In the request body, specify the + changePassword action + followed by attributes. The following table + describes the attributes that you specify in the + request body: + + + + + + + + + + + + + + + + + + +
Change Administrator Password Request + Body Attributes
AttributeDescriptionRequired
adminPassThe administrator password.Yes
This operation does not return a response body. - Server Update Request: XML + Action Change Password Request: XML - Server Update Request: JSON + Action Change Password Request: JSON - This operation does not contain a response body. +
@@ -2492,27 +2772,26 @@ Host: servers.api.openstack.org/v2/ &POST; /servers/id/action - Reboot the specified server + Reboots the specified + server. - - Normal Response Code(s): - 202 + Normal Response Code(s): + 202 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), buildInProgress + (409) @@ -2533,27 +2812,73 @@ Host: servers.api.openstack.org/v2/ + This operation enables you to complete either a + soft or hard reboot of a specified server. With a + soft reboot (SOFT), the operating + system is signaled to restart, which allows for a + graceful shutdown of all processes. A hard reboot + (HARD) is the equivalent of power + cycling the server. + Specify the server ID as + id in the URI. + In the request body, specify the + reboot action followed by + attributes. + The following table describes the attributes + that you specify in the request body: - The reboot function allows for either a soft or - hard reboot of a server. With a soft reboot - (SOFT), the operating system is signaled to - restart, which allows for a graceful shutdown of - all processes. A hard reboot (HARD) is the - equivalent of power cycling the server. + + + + + + + + + + + + + + + + + + + + +
Reboot Server Request + Attributes
AttributeDescriptionRequired
type + The type of reboot: + + SOFT. + The operating system is signaled to + restart, which allows for a + graceful shutdown of all + processes. + + + HARD. + Equivalent to power cycling the + server. + + + No. Default is SOFT.
 + This operation does not return a response + body. - Action Reboot: XML + Action Reboot Request: XML - Action Reboot: JSON + Action Reboot Request: JSON - This operation does not return a response body.
@@ -2570,7 +2895,8 @@ Host: servers.api.openstack.org/v2/ &POST; /servers/id/action - Rebuild the specified server + Rebuilds the specified + server. @@ -2612,22 +2938,83 @@ Host: servers.api.openstack.org/v2/ + The rebuild operation removes all data on the + server and replaces it with the specified image. + The serverRef and all IP + addresses will remain the same. If + name, + metadata, + accessIPv4, or + accessIPv6 are specified, + they will replace existing values, otherwise they + do not change. + A rebuild operation always removes data injected + into the file system through server + personality. You can + reinsert data into the file system during the + rebuild. The full URL to the rebuilt server is + returned through the Location header. + Specify the server ID as + id in the URI. + In the request body, specify the + rebuild action followed by + attributes. + The following table describes the attributes + that you specify in the request body: - The rebuild function removes all data on the - server and replaces it with the specified - image. The serverRef and all - IP addresses will remain the same. If - name, - metadata, - accessIPv4, or - accessIPv6 are specified, they - will replace existing values, otherwise they will - not change. A rebuild operation always removes - data injected into the file system via server - personality. You may - reinsert data into the filesystem during the - rebuild. The full URL to the rebuilt server - is returned via the Location header. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Rebuild Server Request + Attributes
AttributeDescriptionRequired
nameThe new name for the server.Yes
imageRefThe image reference. Specify as an ID or full URL. Yes
accessIPv4The IP version 4 address.No
accessIPv6The IP version 6 address.No
adminPassThe administrator password.Yes
metadataA metadata key and value + pair.No
personalityThe file path and file + contents.No
 Action Rebuild Request: XML @@ -2668,29 +3055,29 @@ Host: servers.api.openstack.org/v2/ &POST; /servers/id/action - Resize the specified server + Resizes the specified + server. - - Normal Response Code(s): - 202 + Normal Response Code(s): + 202 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), resizeNotAllowed (403), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - serverCapacityUnavailable (503), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), + serverCapacityUnavailable + (503), buildInProgress + (409) @@ -2711,30 +3098,69 @@ Host: servers.api.openstack.org/v2/ - - The resize function converts an existing server to - a different flavor, in essence, scaling the server - up or down. The original server is saved for a - period of time to allow rollback if there is a - problem. All resizes should be tested and + The resize operation converts an existing server + to a different flavor, in essence, scaling the + server up or down. The original server is saved + for a period of time to allow rollback if there is + a problem. All resizes should be tested and explicitly confirmed, at which time the original server is removed. All resizes are automatically confirmed after 24 hours if they are not - explicitly confirmed or reverted. - + explicitly confirmed or reverted. + Specify the server ID as + id in the URI. + In the request body, specify the + resize action followed + by attributes. The following table describes the + attributes that you specify in the request + body: + + + + + + + + + + + + + + + + + + + + + + + + + + +
Resize Server Request + Attributes
AttributeDescriptionRequired
nameThe name for the resized + server.Yes
flavorRef + The flavor reference, which + is the endpoint appended with the + following + string:tenant_id/flavors/flavor_id + Yes
+ This operation does not return a response body. - Action Resize: XML + Action Resize Request: XML - Action Resize: JSON + Action Resize Request: JSON - This operation does not return a response body.
@@ -2751,29 +3177,29 @@ Host: servers.api.openstack.org/v2/ &POST; /servers/id/action - Confirm a pending resize action + Confirms a pending resize + action. - - Normal Response Code(s): - 204 + Normal Response Code(s): + 204 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), resizeNotAllowed (403), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - serverCapacityUnavailable (503), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), + serverCapacityUnavailable + (503), buildInProgress + (409) @@ -2792,30 +3218,33 @@ Host: servers.api.openstack.org/v2/ - - During a resize operation, the original server is - saved for a period of time to allow roll back if - there is a problem. Once the newly resized server + During a resize operation, the original server + is saved for a period of time to allow roll back + if a problem exists. Once the newly resized server is tested and has been confirmed to be functioning properly, use this operation to confirm the - resize. After confirmation, the original server - is removed and cannot be rolled back to. All - resizes are automatically confirmed after 24 hours - if they are not explicitly confirmed or reverted. - + resize. After confirmation, the original server is + removed and cannot be rolled back to. All resizes + are automatically confirmed after 24 hours if they + are not explicitly confirmed or reverted. + Specify the server ID as + id in the URI. + In the request body, specify the + confirmResize action. + This operation does not return a response + body. - Action Confirm Resize: XML + Action Confirm Resize Request: XML - Action Confirm Resize: JSON + Action Confirm Resize Request: JSON - This operation does not return a response body.
@@ -2832,29 +3261,29 @@ Host: servers.api.openstack.org/v2/ &POST; /servers/id/action - Cancel and revert a pending resize action + Cancels and reverts a + pending resize action. - - Normal Response Code(s): - 202 + Normal Response Code(s): + 202 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), resizeNotAllowed (403), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - serverCapacityUnavailable (503), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), + serverCapacityUnavailable + (503), buildInProgress + (409) @@ -2875,24 +3304,30 @@ Host: servers.api.openstack.org/v2/ - - During a resize operation, the original server is - saved for a period of time to allow for roll back - if there is a problem. If you determine there is a - problem with a newly resized server, use this - operation to revert the resize and roll back to - the original server. All resizes are automatically - confirmed after 24 hours if they have not already - been confirmed explicitly or reverted. - + During a resize operation, the original server + is saved for a period of time to allow for roll + back if there is a problem. If you determine there + is a problem with a newly resized server, use the + revert resize operation to revert the resize and + roll back to the original server. All resizes are + automatically confirmed after 24 hours if they + have not already been confirmed explicitly or + reverted. + Specify the server ID as + id in the URI. + In the request body, specify the + revertResize action + followed by attributes. + This operation does not return a response + body. - Action Revert Resize: XML + Action Revert Resize Request: XML - Action Revert Resize: JSON + Action Revert Resize Request: JSON @@ -2918,26 +3353,26 @@ Host: servers.api.openstack.org/v2/ - - Normal Response Code(s): - 202 + Normal Response Code(s): + 202 - - Error Response Code(s): - computeFault (400, 500, …), - backupOrResizeInProgress (409), - resizeNotAllowed (403), + Error Response Code(s): computeFault + (400, + 500, …), + backupOrResizeInProgress + (409), resizeNotAllowed + (403), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - serverCapacityUnavailable (503), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), + serverCapacityUnavailable + (503), buildInProgress + (409) @@ -2954,44 +3389,79 @@ Host: servers.api.openstack.org/v2/ - - This action creates a new image for the given + This operation creates a new image for the given server. Once complete, a new image will be available that can be used to rebuild or create - servers. The full URL to the newly created image + servers. The full URL to the newly created image is returned via the Location header, additional attributes for the image including creation status may be retrieved by performing a subsequent &GET; on that URL. See for details. - + linkend="Get_Image_Details-d1e4848"/> for + details. + Custom image metadata can also be supplied when + creating an image. 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 image is determined by the compute + provider and may be queried through the + maxImageMeta absolute limit. + Specify the server ID as + id in the URI. + In the request body, specify the + createImage action followed + by attributes. The following table describes the + attributes that you specify in the request + body: - Custom image metadata can also be supplied when - creating an image. 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 - image is determined by the compute provider and - may be queried via the maxImageMeta absolute - limit. + + + + + + + + + + + + + + + + + + + + + + + + + +
Create Image Request + Attributes
AttributeDescriptionRequired
nameThe name for the new image.Yes
metadata + Key and value pairs for + metadata. + No
 - This operation does not return a response body. + This operation does not return a response + body. - - At present, image creation is an asynchronous - operation, so coordinating the creation with - data quiescence, etc. is currently not - possible. - + At present, image creation is an + asynchronous operation, so coordinating the + creation with data quiescence, and so on is + currently not possible. - Action Create Image: XML + Action Create Image Request: XML - Action Create Image: JSON + Action Create Image Request: JSON
@@ -2999,11 +3469,9 @@ Host: servers.api.openstack.org/v2/
Flavors - - A flavor is an available hardware configuration for a - server. Each flavor has a unique combination of disk - space and memory capacity. - + A flavor is an available hardware configuration for + a server. Each flavor has a unique combination of disk + space and memory capacity.
List Flavors @@ -3022,7 +3490,8 @@ Host: servers.api.openstack.org/v2/ minRam=minRamInMB& marker=markerID&limit=int - List available flavors (IDs, names, links) + Lists IDs, names, and + links for all available flavors. &GET; @@ -3030,37 +3499,68 @@ Host: servers.api.openstack.org/v2/ colspan="2">/flavors/detail?minDisk=minDiskInGB& minRam=minRamInMB& marker=markerID&limit=int - List available flavors (all details) + Lists all details for all + available flavors. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413) + This operation lists information for all + available flavors. + To filter the list of flavors returned in the + response body, you can specify the following + optional parameters in the URI: - This operation will list all available flavors. - The minDisk parameter can - narrow the list of flavors to those which contain - at least the specified number of gigabytes of disk - storage. The minRam - parameter narrows the list of flavors to those - that contain at least the specified amount of RAM - in megabytes. - - - This operation does not require a request body. + + + minDisk=minDiskInGB& + + Filters the list of flavors to + those with the specified minimum + number of gigabytes of disk + storage. + + + + minRam=minRamInMB& + + Filters the list of flavors to + those with the specified minimum + amount of RAM in megabytes. + + + + marker=markerID& + + The ID of the last item in the + previous list. See . + + + + limit=int + + Sets the page size. See . + + + + This operation does not require a request body. Flavors List Response: XML (detail) @@ -3085,27 +3585,31 @@ Host: servers.api.openstack.org/v2/ &GET; /flavors/id - List details of the specified flavor + Lists details of the + specified flavor. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404) - - This operation returns details of the specified flavor. - This operation does not require a request body. + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404) + Specify the flavor ID as + id in the URI. + This operation does not require a request + body. + This operation returns details of the specified + flavor in the response body. Flavor Details Response: XML @@ -3124,11 +3628,9 @@ Host: servers.api.openstack.org/v2/
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. - + 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.
List Images @@ -3149,7 +3651,8 @@ Host: servers.api.openstack.org/v2/ marker=markerID&limit=int& type=(BASE|SERVER) - List available images (IDs, names, links) + Lists IDs, names, and + links for all available images. &GET; @@ -3160,57 +3663,104 @@ Host: servers.api.openstack.org/v2/ marker=markerID&limit=int& type=(BASE|SERVER) - List available images (all details) + Lists all details for all + available images. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413) + This operation lists all images visible by the + account. + To filter the list of images returned in the + response body, you can specify the following + optional parameters in the URI: - This operation will list all images visible by the - account. + + + server=serverRef& + + Filters the list of images by + server. Specify the server + reference by ID or by full + URL. + + + name=imageName& + + Filters the list of images by + image name. + + + status=imageStatus& + + Filters the list of images by + status. In-flight images will have + the status attribute set to + SAVING and the + conditional progress element + (0-100% completion) will also be + returned. Other possible values for + the status attribute include: + UNKNOWN, + ACTIVE, + SAVING, + ERROR, and + DELETED. Images with + an ACTIVE status are + available for install. + + + + changes-since=dateTime& + + Filters the list of images to + those that have changed since the + changes-since time. See for + details. + + + + marker=markerID& + + The ID of the last item in the + previous list. See . + + + + limit=int + + Sets the page size. See . + + + type={BASE|SERVER} + + Filters base images or server + backups. + + + - - In-flight images will have the status attribute - set to SAVING and the conditional - progress element (0-100% completion) will also be - returned. Other possible values for the status - attribute include: UNKNOWN, - ACTIVE, SAVING, - ERROR, and - DELETED. Images with an - ACTIVE status are available for - install. The optional minDisk and minRam - attributes set the minimum disk and RAM - requirements needed to create a server with the - image. - - - The list of images may be filtered by server, - name, and status via the respective query - parameters. A server reference may be specified by - ID or with a full URL. The - type parameter will select - only base images (BASE) or - server backups (SERVER). - When using the changes-since parameter - the list of images will contain images that have - changed since the changes-since time. See - for details. - - This operation does not require a request body. + This operation does not require a request body. + The optional minDisk and minRam attributes set the + minimum disk and RAM requirements needed to create + a server with the image. Images List Response: XML (detail) @@ -3238,27 +3788,30 @@ Host: servers.api.openstack.org/v2/ &GET; /images/id - List details of the specified image + Lists details of the + specified image. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404) - - This operation returns details of the specified image. + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404) + Specify the image ID as + id in the URI. This operation does not require a request body. + This operation returns details of the + specified image in the response body. Image Details Response: XML @@ -3292,21 +3845,19 @@ Host: servers.api.openstack.org/v2/ - - Normal Response Code(s): - 204 + Normal Response Code(s): + 204 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404) @@ -3323,14 +3874,16 @@ Host: servers.api.openstack.org/v2/ - This operation deletes an image from the system. - - Images are immediately removed. Currently, there + This operation deletes the specified image from + the system. + Specify the image ID as + id in the URI. + Images are immediately removed. Currently, there are no state transitions to track the delete - operation. - + operation. This operation does not require a request body. - This operation does not contain a response body. + This operation does not return a response + body.
@@ -3354,36 +3907,35 @@ Host: servers.api.openstack.org/v2/ &GET; /servers/id/metadata - List metadata associated - with a server + Lists metadata associated + with a server. &GET; /images/id/metadata - List metadata associated - with an image + Lists metadata associated + with an image. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404) - - - Lists all metadata. This operation does not - require a request body. - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404) + Lists all metadata. + Specify the server or image ID as + id in the URI. + This operation does not require a request body. Metadata List Response: XML @@ -3412,65 +3964,97 @@ Host: servers.api.openstack.org/v2/ &PUT; /servers/id/metadata - Set metadata + Sets metadata for a + specified server. &PUT; /images/id/metadata - Set metadata + Sets metadata for a + specified image. - - Normal Response Code(s): - 200 + Normal Response Code(s): + 200 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), buildInProgress + (409) + Sets metadata for the specified image or server. + Specify the image or server ID as + id in the URI. + In the request body, specify the + metadata element followed + by attributes. The following table describes the + attributes that you specify in the request + body: - Sets metadata for the resource. Existing metadata - items are replaced with the ones provided in the - request. An overLimit (413) - fault may be thrown if the maximum number of - metadata items is exceeded. The maximum number of - key-value pairs that can be supplied per server is - determined by the compute provider and may be - queried via the maxServerMeta absolute limit. The - maximum number of key-value pairs for an image may - be queried via the maxImageMeta absolute limit. + + + + + + + + + + + + + + + + + + + +
Set Metadata Request + Attributes
AttributeDescriptionRequired
meta + Key and value pairs for + metadata. + Yes
 + Existing metadata items are replaced with the + ones provided in the request. An overLimit + (413) fault may be + thrown if the maximum number of metadata items is + exceeded. The maximum number of key-value pairs + that can be supplied per server is determined by + the compute provider and may be queried via the + maxServerMeta absolute limit. The maximum number + of key-value pairs for an image may be queried via + the maxImageMeta absolute limit. - Metadata Reset Request: XML + Set Metadata Request: XML - Metadata Reset Request: JSON + Set Metadata Request: JSON - Metadata Reset Response: XML + Set Metadata Response: XML - Metadata Reset Response: JSON + Set Metadata Response: JSON @@ -3491,67 +4075,99 @@ Host: servers.api.openstack.org/v2/ &POST; /servers/id/metadata - Update metadata items + Updates metadata items for + the specified server. &POST; /images/id/metadata - Update metadata items + Updates metadata items for + the specified image. - - Normal Response Code(s): - 200 + Normal Response Code(s): + 200 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - buildInProgress (409) - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), buildInProgress + (409) + Updates resource metadata. + Specify the image or server ID as + id in the URI. + In the request body, specify the + metadata element followed + by attributes. The following table describes the + attributes that you specify in the request + body: - Updates resource metadata. Updates will replace - existing metadata items with the same key. Items - not explicitly mentioned in the request will not be - modified. An overLimit (413) - fault may be thrown if the operation causes the - maximum number of metadata items to be exceeded. - The maximum number of key-value pairs that can be - supplied per server is determined by the compute - provider and may be queried via the maxServerMeta - absolute limit. The maximum number of key-value - pairs for an image may be queried via the - maxImageMeta absolute limit. + + + + + + + + + + + + + + + + + + + +
Update Metadata Request + Attributes
AttributeDescriptionRequired
meta + Key and value pairs for + metadata. + Yes
 + Updates will replace existing metadata items + with the same key. Items not explicitly mentioned + in the request will not be modified. An overLimit + (413) fault may be + thrown if the operation causes the maximum number + of metadata items to be exceeded. The maximum + number of key-value pairs that can be supplied per + server is determined by the compute provider and + may be queried via the maxServerMeta absolute + limit. The maximum number of key-value pairs for + an image may be queried via the maxImageMeta + absolute limit. - Metadata Update Request: XML + Update Metadata Request: XML - Metadata Update Request: JSON + Update Metadata Request: JSON - Metadata Update Response: XML + Update Metadata Response: XML - Metadata Update Response: JSON + Update Metadata Response: JSON @@ -3572,38 +4188,36 @@ Host: servers.api.openstack.org/v2/ &GET; /servers/id/metadata/key - Get metadata item - associated - with a server + Gets a metadata item + associated with a server. &GET; /images/id/metadata/key - Get metadata item - associated - with an image + Gets a metadata item + associated with an image. - - Normal Response Code(s): - 200, 203 + Normal Response Code(s): + 200, + 203 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404) - - - Retrieves a single metadata item by key. The - operation does not require a request body. - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404) + Retrieves a single metadata item by key. + In the URI, specify the image or server ID as + id and the key as + key. + This operation does not require a request body. Metadata Item Response: XML @@ -3632,64 +4246,94 @@ Host: servers.api.openstack.org/v2/ &PUT; /servers/id/metadata/key - Set a metadata item + Sets a metadata item for a + specified server. &PUT; /images/id/metadata/key - Set a metadata item + Sets a metadata item for a + specified image. - - Normal Response Code(s): - 200 + Normal Response Code(s): + 200 - - Error Response Code(s): - computeFault (400, 500, …), + Error Response Code(s): computeFault + (400, + 500, …), serviceUnavailable (503), unauthorized (401), - forbidden (403), - badRequest (400), - badMethod (405), - overLimit (413), - itemNotFound (404), - badMediaType (415), - buildInProgress (409) - - - Sets a metadata item by its key. An overLimit - (413) fault may be thrown - if the operation causes the maximum number of - metadata items to be exceeded. The maximum number - of key-value pairs that can be supplied per server - is determined by the compute provider and may be - queried via the maxServerMeta absolute limit. The - maximum number of key-value pairs for an image may - be queried via the maxImageMeta absolute limit. - + forbidden (403), badRequest + (400), badMethod + (405), overLimit + (413), itemNotFound + (404), badMediaType + (415), buildInProgress + (409) + Sets a metadata item by its key. + In the URI, specify the image or server ID as + id and the key as + key. + In the request body, specify the + metadata element followed + by attributes. The following table describes the + attributes that you specify in the request + body: + + + + + + + + + + + + + + + + + + + +
Set Metadata Item Request + Attributes
AttributeDescriptionRequired
meta + Key and value pairs for + metadata. + Yes
An overLimit (413) + fault may be thrown if the operation causes the + maximum number of metadata items to be exceeded. + The maximum number of key-value pairs that can be + supplied per server is determined by the compute + provider and may be queried via the maxServerMeta + absolute limit. The maximum number of key-value + pairs for an image may be queried via the + maxImageMeta absolute limit. - Metadata Item Update Request: XML + Set Metadata Item Request: XML - Metadata Item Update Request: JSON + Set Metadata Item Request: JSON - Metadata Item Update Response: XML + Set Metadata Item Response: XML - Metadata Item Update Response: JSON + Set Metadata Item Response: JSON @@ -3710,12 +4354,14 @@ Host: servers.api.openstack.org/v2/ &DELETE; /servers/id/metadata/key - Deletes a metadata item + Deletes a metadata item + for the specified server. &DELETE; /images/id/metadata/key - Deletes a metadata item + Deletes a metadata item + for the specified image. @@ -3735,11 +4381,12 @@ Host: servers.api.openstack.org/v2/ itemNotFound (404), buildInProgress (409) - - Deletes a metadata item. The operation does not - require a request body and does not contain a - response body. - + Deletes a metadata item. + In the URI, specify the image or server ID as + id and the key as + key. + The operation does not require a request body. + The operation does not return a response body.
diff --git a/openstack-compute-api-2/src/samples/server-put-resp.json b/openstack-compute-api-2/src/samples/server-put-resp.json index 86bb337..31ad2e4 100644 --- a/openstack-compute-api-2/src/samples/server-put-resp.json +++ b/openstack-compute-api-2/src/samples/server-put-resp.json @@ -75,4 +75,4 @@ } ] } -} +} \ No newline at end of file