openstack/glance
Code Issues Proposed changes
glance/api-ref/source/v1/images-images-v1.inc
bria4010 ee1b6dce3c WADL to RST migration (part 1) 
This brings the Images API Reference to the glance tree as part of
the effort described here:
https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan

This patch introduces (a) the tox environment to generate the api-ref,
and (b) the content of the Images v1 API reference converted to RST.
The content has been corrected where I noticed divergences with reality.

Note to reviewers: The conversion project is ongoing, that is, the doc
team is continuing to develop tools (for example, to display the response
codes in a table) and converging on a style for these docs.  So this isn't
a final product, there will be more patches later.  While this patch is
not perfect, it is pareto-optimal with respect to content (it's at least
as good as the current guide, and better in at least one place).  Thus
my advice, should you choose to take it, is that we should merge this
patch to get these docs in-tree, and make improvements as additional
patches that can focus on particular API calls rather than try to get
everything perfect on this patch.

Change-Id: I51dfaf1832108466f115ab183838c5f28e138312
2016-06-21 13:29:24 -04:00

345 lines
7.7 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
Images
******
Create image
~~~~~~~~~~~~
.. rest_method:: POST /v1/images
Creates a metadata record of a virtual machine (VM) image and optionally
stores the image data.
Image metadata fields are passed as HTTP headers prefixed with one of
the strings ``x-image-meta-`` or ``x-image-meta-property-``. See the
API documentation for details.
If there is no request body, an image record will be created in status
``queued``. This is called *reserving an image*. The image data can be
uploaded later using the `Update image`_ call.
If image data will be uploaded as part of this request, then the following
image metadata must be included among the request headers:
- ``name``
- ``disk_format``
- ``container_format``
Additionally, if image data is uploaded as part of this request, the API
will return a 400 under the following circumstances:
- The ``x-image-meta-size`` header is present and the length in bytes of
the request body does not match the value of this header.
- The ``x-image-meta-checksum`` header is present and MD5 checksum generated
by the backend store while storing the data does not match the value of
this header.
Normal response codes: 201
Error response codes: 400, 409
Request
-------
.. rest_parameters:: parameters.yaml
- image data: createImage
- x-image-meta-name: x-image-meta-name
- x-image-meta-container_format: x-image-meta-container_format
- x-image-meta-disk_format: x-image-meta-disk_format
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- location: location
- image: image-object
Response Example (create with data)
-----------------------------------
::
HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 491
Location: http://glance.example.com/v1/images/de2f2211-3ac7-4260-9142-41db0ecfb425
Etag: 7b1b10607acc1319506185e7227ca30d
X-Openstack-Request-Id: req-70adeab4-740c-4db3-a002-fd1559ecf40f
Date: Tue, 10 May 2016 21:41:41 GMT
.. literalinclude:: samples/images-create-with-data-response.json
:language: json
Response Example (reserve an image)
-----------------------------------
This is an extreme example of reserving an image. It was created by a POST
with no headers specified and no data passed. Here's the response:
::
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 447
Location: http://glance.example.com/v1/images/6b3ecfca-d445-4946-a8d1-c4938352b251
X-Openstack-Request-Id: req-db1ff3c7-3d4f-451f-9ef1-c414343f809d
Date: Tue, 10 May 2016 21:35:14 GMT
.. literalinclude:: samples/images-create-reserve-response.json
:language: json
List images
~~~~~~~~~~~
.. rest_method:: GET /v1/images
Lists all VM images available to the user making the call. This list will
include all public images, any images owned by the requestor, and any images
shared with the requestor.
Various query filters can be applied to the URL to restrict the content of
the response.
Normal response codes: 200
Error response codes: 400, 403
.. note:: need to add info about sorting and pagination
Request
-------
.. rest_parameters:: parameters.yaml
- name: name-in-query
- container_format: container_format-in-query
- disk_format: disk_format-in-query
- status: status-in-query
- size_min: size_min
- size_max: size_max
- changes-since: changes-since
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- images: images-list
Response Example
----------------
.. literalinclude:: samples/images-list-response.json
:language: json
List images with details
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v1/images/detail
Lists all available images with details.
Various query filters can be applied to the URL to restrict the content of
the response.
Normal response codes: 200
Error response codes: 400, 403
.. note:: need to add info about sorting and pagination
Request
-------
.. rest_parameters:: parameters.yaml
- name: name-in-query
- container_format: container_format-in-query
- disk_format: disk_format-in-query
- status: status-in-query
- size_min: size_min
- size_max: size_max
- changes-since: changes-since
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- images: images-detail-list
- previous: previous
- next: next
Response Example
----------------
.. literalinclude:: samples/images-list-details-response.json
:language: json
Update image
~~~~~~~~~~~~
.. rest_method:: PUT /v1/images/{image_id}
Updates the metadata for an image or uploads an image file.
Image metadata is updated by passing HTTP headers prefixed with one of the
strings ``x-image-meta-`` or ``x-image-meta-property-``. See the API
documentation for details.
If the image is in ``queued`` status, image data may be added by
including it in the request body. Otherwise, attempting to add data
will result in a 409 Conflict response.
If the request contains a body, the API will return a 400 under the following
circumstances:
- The ``x-image-meta-size`` header is present and the length in bytes of
the request body does not match the value of this header.
- The ``x-image-meta-checksum`` header is present and MD5 checksum generated
by the backend store while storing the data does not match the value of
this header.
Normal response codes: 200
Error response codes: 400, 404, 409
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id-in-path
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- image: image-object
Response Example
----------------
.. literalinclude:: samples/image-update-response.json
:language: json
Show image details and image data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v1/images/{image_id}
Returns the image metadata as headers; the image data is returned in the
body of the response.
Standard image properties are returned in headers prefixed by
``x-image-meta-`` (for example, ``x-image-meta-name``). Custom image
properties are returned in headers prefixed by the string
``x-image-meta-property-`` (for example, ``x-image-meta-property-foo``).
Normal response codes: 200
Error response codes: 404, 403
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id-in-path
Show image metadata
~~~~~~~~~~~~~~~~~~~
.. rest_method:: HEAD /v1/images/{image_id}
Returns the image metadata information as response headers.
The Image system does not return a response body for the HEAD
operation.
If the request succeeds, the operation returns the ``200`` response
code.
Normal response codes: 200
Error response codes: 404, 409
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id-in-path
Response Example
----------------
::
X-Image-Meta-Checksum: 8a40c862b5735975d82605c1dd395796
X-Image-Meta-Container_format: aki
X-Image-Meta-Created_at: 2016-01-06T03:22:20.000000
X-Image-Meta-Deleted: false
X-Image-Meta-Disk_format: aki
X-Image-Meta-Id: 03bc0a8b-659c-4de9-b6bd-13c6e86e6455
X-Image-Meta-Is_public: true
X-Image-Meta-Min_disk: 0
X-Image-Meta-Min_ram: 0
X-Image-Meta-Name: cirros-0.3.4-x86_64-uec-kernel
X-Image-Meta-Owner: 13cc6052265b41529e2fd0fc461fa8ef
X-Image-Meta-Protected: false
X-Image-Meta-Size: 4979632
X-Image-Meta-Status: deactivated
X-Image-Meta-Updated_at: 2016-02-25T03:02:05.000000
X-Openstack-Request-Id: req-d5208320-28ed-4c22-b628-12dc6456d983
Delete image
~~~~~~~~~~~~
.. rest_method:: DELETE /v1/images/{image_id}
Deletes an image.
Normal response codes: 204
Error response codes: 404, 403
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id-in-path
View Git Blame Copy Permalink