c028c2d23e
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 contains the content of the Images v2 API reference converted to RST. The content has been corrected where I noticed divergences with reality (which actually happened a lot, so this patch contains a lot of revisions). Tasks and metadefs are submitted as separate patches. Change-Id: If69c469da7f28f090a2286ec0b115d9bcaac4fbf Closes-Bug: #1550457 Closes-Bug: #1589264 Closes-Bug: #1592715
588 lines
15 KiB
YAML
588 lines
15 KiB
YAML
# variables in header
|
|
Content-Length:
|
|
description: |
|
|
The length of the body in octets (8-bit bytes)
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Md5:
|
|
description: |
|
|
The MD5 checksum of the body.
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Range:
|
|
description: |
|
|
The content range of image data. For details, see
|
|
`Hypertext Transfer Protocol (HTTP/1.1): Range Requests
|
|
<http://tools.ietf.org/html/rfc7233>`_.
|
|
in: header
|
|
required: false
|
|
type: string
|
|
Content-Type-data:
|
|
description: |
|
|
The media type descriptor for the request body. Use
|
|
``application/octet-stream``
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Type-data-response:
|
|
description: |
|
|
The media type descriptor of the response body, namely
|
|
``application/octet-stream``
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Type-json:
|
|
description: |
|
|
The media type descriptor for the request body. Use
|
|
``application/json``.
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Type-patch:
|
|
description: |
|
|
The media type descriptor for the request body. Use
|
|
``application/openstack-images-v2.1-json-patch``. (You can also use
|
|
``application/openstack-images-v2.0-json-patch``, but keep in mind that
|
|
it's deprecated.)
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Location:
|
|
description: |
|
|
The URL to access the image file from the
|
|
external store.
|
|
in: header
|
|
required: true
|
|
type: string
|
|
|
|
# variables in path
|
|
image_id-in-path:
|
|
description: |
|
|
The UUID of the image.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
member_id-in-path:
|
|
description: |
|
|
The ID of the image member. An image member is usually the project (also
|
|
called the "tenant") with whom the image is shared.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
tag-in-path:
|
|
description: |
|
|
The image tag. A tag is limited to 255 chars in length. You may wish
|
|
to use characters that can easily be written in a URL.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
|
|
# variables in query
|
|
created_at-in-query:
|
|
description: |
|
|
Specify a *comparison filter* based on the date and time when the resource
|
|
was created. (See :ref:`Time Comparison Filters <v2-comparison-ops>`).
|
|
|
|
The date and time stamp format is `ISO 8601
|
|
<https://en.wikipedia.org/wiki/ISO_8601>`_:
|
|
|
|
::
|
|
|
|
CCYY-MM-DDThh:mm:ss±hh:mm
|
|
|
|
The ``±hh:mm`` value, if included, is the time zone as an offset
|
|
from UTC.
|
|
|
|
For example, ``2015-08-27T09:49:58-05:00``.
|
|
|
|
If you omit the time zone, the UTC time zone is assumed.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
limit:
|
|
description: |
|
|
Requests a page size of items. Returns a number of items up to a limit
|
|
value. Use the ``limit`` parameter to make an initial limited request and
|
|
use the ID of the last-seen item from the response as the ``marker``
|
|
parameter value in a subsequent limited request.
|
|
in: query
|
|
required: false
|
|
type: integer
|
|
marker:
|
|
description: |
|
|
The ID of the last-seen item. Use the ``limit`` parameter to make an
|
|
initial limited request and use the ID of the last-seen item from the
|
|
response as the ``marker`` parameter value in a subsequent limited request.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
member_status-in-query:
|
|
description: |
|
|
Filters the response by a member status. A valid value is ``accepted``,
|
|
``pending``, ``rejected``, or ``all``. Default is ``accepted``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
name-in-query:
|
|
description: |
|
|
Filters the response by a name, as a string. A valid value is the name of
|
|
an image.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
owner-in-query:
|
|
description: |
|
|
Filters the response by a project (also called a "tenant") ID. Shows only
|
|
images that are shared with you by the specified owner.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
size_max:
|
|
description: |
|
|
Filters the response by a maximum image size, in
|
|
bytes.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
size_min:
|
|
description: |
|
|
Filters the response by a minimum image size, in
|
|
bytes.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
sort:
|
|
description: |
|
|
Sorts the response by one or more attribute and sort direction
|
|
combinations. You can also set multiple sort keys and directions.
|
|
Default direction is ``desc``.
|
|
|
|
Use the comma (``,``) character to separate multiple values. For
|
|
example:
|
|
|
|
.. code-block:: json
|
|
|
|
GET /v2/images?sort=name:asc,status:desc
|
|
in: query
|
|
required: false
|
|
type: string
|
|
sort_dir:
|
|
description: |
|
|
Sorts the response by a set of one or more sort
|
|
direction and attribute (``sort_key``) combinations. A valid value
|
|
for the sort direction is ``asc`` (ascending) or ``desc``
|
|
(descending). If you omit the sort direction in a set, the default
|
|
is ``desc``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
sort_key:
|
|
description: |
|
|
Sorts the response by an attribute, such as
|
|
``name``, ``id``, or ``updated_at``. Default is ``created_at``.
|
|
The API uses the natural sorting direction of the ``sort_key``
|
|
image attribute.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
status-in-query:
|
|
description: |
|
|
Filters the response by an image status.
|
|
in: query
|
|
required: false
|
|
type: integer
|
|
tag-in-query:
|
|
description: |
|
|
Filters the response by the specified tag value. May be repeated, but keep
|
|
in mind that you're making a conjunctive query, so only images containing
|
|
*all* the tags specified will appear in the response.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
updated_at-in-query:
|
|
description: |
|
|
Specify a *comparison filter* based on the date and time when the resource
|
|
was most recently modified. (See :ref:`Time Comparison Filters
|
|
<v2-comparison-ops>`).
|
|
|
|
The date and time stamp format is `ISO 8601
|
|
<https://en.wikipedia.org/wiki/ISO_8601>`_:
|
|
|
|
::
|
|
|
|
CCYY-MM-DDThh:mm:ss±hh:mm
|
|
|
|
The ``±hh:mm`` value, if included, is the time zone as an offset
|
|
from UTC.
|
|
|
|
For example, ``2015-08-27T09:49:58-05:00``.
|
|
|
|
If you omit the time zone, the UTC time zone is assumed.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
visibility-in-query:
|
|
description: |
|
|
Filters the response by an image visibility value. A valid value is
|
|
``public``, ``private``, or ``shared``. (Note that if you filter on
|
|
``shared``, the images included in the response will only be those where
|
|
your member status is ``accepted`` unless you explicitly include a
|
|
``member_status`` filter in the request.) If you omit this parameter, the
|
|
response shows ``public``, ``private``, and those ``shared`` images with a
|
|
member status of ``accepted``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
|
|
# variables in body
|
|
checksum:
|
|
description: |
|
|
Hash that is used over the image data. The Image
|
|
service uses this value for verification. The value might be
|
|
``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: string
|
|
container_format:
|
|
description: |
|
|
Format of the image container. A valid value is one of
|
|
``ami``, ``ari``, ``aki``, ``bare``, ``ovf``, ``ova``, or
|
|
``docker``. The value might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: enum
|
|
container_format-in-request:
|
|
description: |
|
|
Format of the image container. A valid value is one of
|
|
``ami``, ``ari``, ``aki``, ``bare``, ``ovf``, ``ova``, or
|
|
``docker``.
|
|
in: body
|
|
required: false
|
|
type: enum
|
|
created_at:
|
|
description: |
|
|
The date and time when the resource was created.
|
|
|
|
The date and time stamp format is `ISO 8601
|
|
<https://en.wikipedia.org/wiki/ISO_8601>`_:
|
|
|
|
::
|
|
|
|
CCYY-MM-DDThh:mm:ss±hh:mm
|
|
|
|
For example, ``2015-08-27T09:49:58-05:00``.
|
|
|
|
The ``±hh:mm`` value, if included, is the time zone as an offset
|
|
from UTC.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
direct_url:
|
|
description: |
|
|
The URL to access the image file kept in external store. *It is present
|
|
only if the* ``show_image_direct_url`` *option is* ``true`` *in the Image
|
|
service's configuration file.* **Because it presents a security risk, this
|
|
option is disabled by default.**
|
|
in: body
|
|
required: false
|
|
type: string
|
|
disk_format:
|
|
description: |
|
|
The format of the disk. A valid value is ``ami``, ``ari``, ``aki``,
|
|
``vhd``, ``vmdk``, ``raw``, ``qcow2``, ``vdi``, or ``iso``. The value
|
|
might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: enum
|
|
disk_format-in-request:
|
|
description: |
|
|
The format of the disk. A valid value is ``ami``, ``ari``, ``aki``,
|
|
``vhd``, ``vmdk``, ``raw``, ``qcow2``, ``vdi``, or ``iso``.
|
|
in: body
|
|
required: false
|
|
type: enum
|
|
file:
|
|
description: |
|
|
The URL for the virtual machine image file.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
first:
|
|
description: |
|
|
The URI for the first page of response.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
id:
|
|
description: |
|
|
A unique, user-defined image UUID, in the format:
|
|
|
|
::
|
|
|
|
nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
|
|
|
|
Where **n** is a hexadecimal digit from 0 to f, or F.
|
|
|
|
For example:
|
|
|
|
::
|
|
|
|
b2173dd3-7ad6-4362-baa6-a68bce3565cb
|
|
|
|
If you omit this value, the API generates a UUID for the image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
id-in-request:
|
|
description: |
|
|
A unique, user-defined image UUID, in the format:
|
|
|
|
::
|
|
|
|
nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
|
|
|
|
Where **n** is a hexadecimal digit from 0 to f, or F.
|
|
|
|
For example:
|
|
|
|
::
|
|
|
|
b2173dd3-7ad6-4362-baa6-a68bce3565cb
|
|
|
|
If you omit this value, the API generates a UUID for the image. If you
|
|
specify a value that has already been assigned, the request fails with
|
|
a ``409`` response code.
|
|
in: body
|
|
required: false
|
|
type: string
|
|
image_id-in-body:
|
|
description: |
|
|
The UUID of the image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
images:
|
|
description: |
|
|
A list of *image* objects, as described by the :ref:`Images Schema
|
|
<images-schema>`.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
locations:
|
|
description: |
|
|
A list of objects, each of which describes an image location. Each object
|
|
contains a ``url`` key, whose value is a URL specifying a location, and a
|
|
``metadata`` key, whose value is a dict of key:value pairs containing
|
|
information appropriate to the use of whatever external store is indicated
|
|
by the URL. *This list appears only if the* ``show_multiple_locations``
|
|
*option is set to* ``true`` *in the Image service's configuration file.*
|
|
**Because it presents a security risk, this option is disabled by
|
|
default.**
|
|
in: body
|
|
required: false
|
|
type: array
|
|
member_id:
|
|
description: |
|
|
The ID of the image member. An image member is usually a project (also
|
|
called the "tenant") with whom the image is shared.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
member_status:
|
|
description: |
|
|
The status of this image member. Value is one of ``pending``,
|
|
``accepted``, ``rejected``.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
members:
|
|
description: |
|
|
A list of *member* objects, as described by the :ref:`Image Members Schema
|
|
<image-members-schema>`. Each *member* object describes a member with whom
|
|
this image is being shared.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
min_disk:
|
|
description: |
|
|
Amount of disk space in GB that is required to boot the image.
|
|
The value might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: integer
|
|
min_disk-in-request:
|
|
description: |
|
|
Amount of disk space in GB that is required to boot the image.
|
|
in: body
|
|
required: false
|
|
type: integer
|
|
min_ram:
|
|
description: |
|
|
Amount of RAM in MB that is required to boot the image.
|
|
The value might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: integer
|
|
min_ram-in-request:
|
|
description: |
|
|
Amount of RAM in MB that is required to boot the image.
|
|
in: body
|
|
required: false
|
|
type: integer
|
|
name:
|
|
description: |
|
|
The name of the image. Value might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: string
|
|
name-in-request:
|
|
description: |
|
|
The name of the image.
|
|
in: body
|
|
required: false
|
|
type: string
|
|
next:
|
|
description: |
|
|
The URI for the next page of response. Will not be present on the last
|
|
page of the response.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
owner:
|
|
description: |
|
|
An identifier for the owner of the image, usually the project (also
|
|
called the "tenant") ID.
|
|
The value might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: string
|
|
protected:
|
|
description: |
|
|
A boolean value that must be ``false`` or the image cannot be deleted.
|
|
in: body
|
|
required: true
|
|
type: boolean
|
|
protected-in-request:
|
|
description: |
|
|
Image protection for deletion. Valid value is ``true`` or ``false``.
|
|
Default is ``false``.
|
|
in: body
|
|
required: false
|
|
type: boolean
|
|
schema-image:
|
|
description: |
|
|
The URL for the schema describing a virtual machine image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
schema-images:
|
|
description: |
|
|
The URL for the schema describing a list of images.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
schema-member:
|
|
description: |
|
|
The URL for the schema describing an image member.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
schema-members:
|
|
description: |
|
|
The URL for the schema describing an image member list.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
self:
|
|
description: |
|
|
The URL for the virtual machine image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
size:
|
|
description: |
|
|
The size of the image data, in bytes. The value
|
|
might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: integer
|
|
status:
|
|
description: |
|
|
The image status.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
tags:
|
|
description: |
|
|
List of tags for this image, possibly an empty list.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
tags-in-request:
|
|
description: |
|
|
List of tags for this image. Each tag is a string of at most 255 chars.
|
|
The maximum number of tags allowed on an image is set by the operator.
|
|
in: body
|
|
required: false
|
|
type: array
|
|
updated_at:
|
|
description: |
|
|
The date and time when the resource was updated.
|
|
|
|
The date and time stamp format is `ISO 8601
|
|
<https://en.wikipedia.org/wiki/ISO_8601>`_:
|
|
|
|
::
|
|
|
|
CCYY-MM-DDThh:mm:ss±hh:mm
|
|
|
|
For example, ``2015-08-27T09:49:58-05:00``.
|
|
|
|
The ``±hh:mm`` value, if included, is the time zone as an offset
|
|
from UTC. In the previous example, the offset value is ``-05:00``.
|
|
|
|
If the ``updated_at`` date and time stamp is not set, its value is
|
|
``null``.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
url:
|
|
description: |
|
|
The URL to access the image file kept in external
|
|
store.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
value:
|
|
description: |
|
|
Value of image property used in add or replace
|
|
operations expressed in JSON notation. For example, you must
|
|
enclose strings in quotation marks, and you do not enclose numeric
|
|
values in quotation marks.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
virtual_size:
|
|
description: |
|
|
The virtual size of the image. The value might
|
|
be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: integer
|
|
visibility:
|
|
description: |
|
|
Image visibility, that is, the access permission for the image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
visibility-in-request:
|
|
description: |
|
|
Visibility for this image. Valid value is ``public`` or ``private``.
|
|
At most sites, only an administrator can make an image public.
|
|
Default is ``private``.
|
|
in: body
|
|
required: false
|
|
type: string
|