openstack/nova
Code Issues Proposed changes
62b3192c70
nova/api-ref/source/images.inc
Monty Taylor e7cc5efd20 Keep pre-commit inline with hacking and fix whitespace 
The flake8 hook for pre-commit installs its own flake8 which is
not what hacking is pinned to. This results in a bunch of errors.
By doing a local hook we can cause these to be the same.

There are flake8 exclusions in tox.ini that need to be used
in pre-commit. Also we should exclude svg files from the whitespace
modifications, because who cares.

Once those are fixed, running pre-commit -a fixes some whitespace
issues. While the normal use isn't to run -a - if someone does make
a patch that touches any of these they'll get erroneous unrelated
errors compared to their lower work - so fix all of the existing
issues, which are mostly space-at-end-of-line issues it seems.

Change-Id: I78e753492e99c03b30a0a691db3bd75ee3d289c9
2019-12-12 14:56:39 +00:00

383 lines
7.8 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
====================
Images (DEPRECATED)
====================
.. warning::
These APIs are proxy calls to the Image service. Nova has
deprecated all the proxy APIs and users should use the native APIs
instead. All the Image services proxy APIs except image metadata
APIs will fail with a 404 starting from microversion 2.36.
The image metadata APIs will fail with a 404 starting from
microversion 2.39.
See: `Relevant Image APIs
<https://docs.openstack.org/api-ref/image/v2/index.html>`__.
Lists, shows details and deletes images.
Also sets, lists, shows details, create, update and deletes image metadata.
An image is a collection of files that you use to create and rebuild a
server. By default, operators provide pre-built operating system images.
You can also create custom images. See: `Create Image Action
<https://docs.openstack.org/api-ref/compute/#create-image-createimage-action>`__.
By default, the ``policy.json`` file authorizes all users to view the
image size in the ``OS-EXT-IMG-SIZE:size`` extended attribute.
List Images
===========
.. rest_method:: GET /images
List images.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- changes-since: changes-since
- server: image_server_query
- name: image_name_query
- status: image_status_query
- minDisk: minDisk
- minRam: minRam
- type : image_type_query
- limit : limit
- marker : marker
Response
--------
.. rest_parameters:: parameters.yaml
- images: images
- id: image_id_body
- name: image_name
- links: links
**Example List Images: JSON response**
.. literalinclude:: ../../doc/api_samples/images/images-list-get-resp.json
:language: javascript
List Images With Details
========================
.. rest_method:: GET /images/detail
List images with details.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- changes-since: changes-since
- server: image_server_query
- name: image_name_query
- status: image_status_query
- minDisk: minDisk
- minRam: minRam
- type : image_type_query
- limit : limit
- marker : marker
Response
--------
.. rest_parameters:: parameters.yaml
- images: images
- id: image_id_body
- name: image_name
- minRam: minRam_body
- minDisk: minDisk_body
- metadata: metadata_object
- created: created
- updated: updated
- status: image_status
- progress: image_progress
- links: links
- server: image_server
- OS-EXT-IMG-SIZE:size: image_size
- OS-DCF:diskConfig: OS-DCF:diskConfig
**Example List Images Details: JSON response**
.. literalinclude:: ../../doc/api_samples/images/images-details-get-resp.json
:language: javascript
Show Image Details
==================
.. rest_method:: GET /images/{image_id}
Shows details for an image.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
Response
--------
.. rest_parameters:: parameters.yaml
- images: images
- id: image_id_body
- name: image_name
- minRam: minRam_body
- minDisk: minDisk_body
- metadata: metadata_object
- created: created
- updated: updated
- status: image_status
- progress: image_progress
- links: links
- server: image_server
- OS-EXT-IMG-SIZE:size: image_size
- OS-DCF:diskConfig: OS-DCF:diskConfig
**Example Show Image Details: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-get-resp.json
:language: javascript
Delete Image
============
.. rest_method:: DELETE /images/{image_id}
Deletes an image.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
Response
--------
There is no body content for the response of a successful DELETE action.
List Image Metadata
===================
.. rest_method:: GET /images/{image_id}/metadata
List metadata of an image.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example List Image Metadata Details: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-get-resp.json
:language: javascript
Create Image Metadata
=====================
.. rest_method:: POST /images/{image_id}/metadata
Create an image metadata.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- metadata: metadata_object
**Example Create Image Metadata: JSON request**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example Create Image Metadata: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-post-resp.json
:language: javascript
Update Image Metadata
=====================
.. rest_method:: PUT /images/{image_id}/metadata
Update an image metadata
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- metadata: metadata_object
**Example Update Image Metadata: JSON request**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- metadata: metadata_object
**Example Update Image Metadata: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-metadata-put-resp.json
:language: javascript
Show Image Metadata Item
========================
.. rest_method:: GET /images/{image_id}/metadata/{key}
Shows metadata item, by key, for an image.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- key: key
Response
--------
.. rest_parameters:: parameters.yaml
- meta: meta
**Example Show Image Metadata Item Details: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-meta-key-get.json
:language: javascript
Create Or Update Image Metadata Item
====================================
.. rest_method:: PUT /images/{image_id}/metadata/{key}
Creates or updates a metadata item, by key, for an image.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- key: key
- meta: meta
**Example Create Or Update Image Metadata Item: JSON request**
.. literalinclude:: ../../doc/api_samples/images/image-meta-key-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- meta: meta
**Example Create Or Update Image Metadata Item: JSON response**
.. literalinclude:: ../../doc/api_samples/images/image-meta-key-put-resp.json
:language: javascript
Delete Image Metadata Item
==========================
.. rest_method:: DELETE /images/{image_id}/metadata/{key}
Deletes a metadata item, by key, for an image.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id
- key: key
Response
--------
There is no body content for the response of a successful DELETE action.
View Git Blame Copy Permalink