openstack/glance
Code Issues Proposed changes

Merge "Remove v1 from API ref"

Browse Source
This commit is contained in:
Zuul 2018-03-06 14:33:39 +00:00 committed by Gerrit Code Review
commit c9f2772e4e
16 changed files with 5 additions and 946 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
api-ref/source/index.rst
View File

@ -26,4 +26,3 @@ API content can be searched using the :ref:`search`.
versions/index
v2/index
v2/metadefs-index
v1/index

344
api-ref/source/v1/images-images-v1.inc
View File

@ -1,344 +0,0 @@
.. -*- 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.openstack.example.org/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.openstack.example.org/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

150
api-ref/source/v1/images-sharing-v1.inc
View File

@ -1,150 +0,0 @@
.. -*- rst -*-
Sharing
*******
Image sharing provides a means for one tenant (the "producer") to make a
private image available to other tenants (the "consumers"). This ability
can unfortunately be misused to spam tenants' image lists, so these calls
may not be exposed in some deployments. (The Images v2 API has a more
sophisticated sharing scheme that contains an anti-spam provision.)
Add member to image
~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v1/images/{image_id}/members/{member_id}
Adds the tenant whose tenant ID is ``member_id`` as a member of the
image denoted by ``image_id``.
By default, an image member cannot further share the image with other
tenants. This behavior can be overridden by supplying a request body
with the call that specifies ``can_share`` as ``true``.
Thus:
- If you omit the request body, this call adds the specified tenant as a
member of the image with the ``can_share`` attribute set to ``false``.
- If you include a request body, the ``can_share`` attribute will be set
to the appropriate boolean value you have supplied in the request body.
- If the specified tenant is already a member, and there is no request
body, the membership (including the ``can_share`` attribute) remains
unmodified.
- If the specified tenant is already a member and the request includes
a body, the ``can_share`` attribute of the tenant will be set to whatever
value is specified in the request body.
Normal response codes: 204
Error response codes: 404
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id-in-path
- member_id: member_id-in-path
- can_share: can_share
- member_id: member_id
Request Example
---------------
.. literalinclude:: samples/image-member-add-request.json
:language: json
Replace membership list for an image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v1/images/{image_id}/members
Replaces the membership list for an image so that the tenants whose
tenant IDs are listed in the member objects comprising the request body
become all and only the members of the image denoted by ``image_id``.
If the ``can_share`` attribute is omitted for in any member object:
- If the member already exists on the image, that member's ``can_share``
setting remains unchanged.
- If the member did not already exist on the image, that member's
``can_share`` attribute is set to ``false``.
Normal response codes: 204
Error response codes: 404
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id-in-path
- memberships: memberships
Request Example
---------------
.. literalinclude:: samples/image-members-add-request.json
:language: json
Remove member
~~~~~~~~~~~~~
.. rest_method:: DELETE /v1/images/{image_id}/members/{member_id}
Removes a member from an image.
Normal response codes: 204
Error response codes: 404
Request
-------
.. rest_parameters:: parameters.yaml
- image_id: image_id-in-path
- member_id: member_id-in-path
List shared images
~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v1/shared-images/{owner_id}
Lists the VM images that an owner shares. The ``owner_id`` is the tenant ID
of the image owner.
Normal response codes: 200
Error response codes: 404
Request
-------
.. rest_parameters:: parameters.yaml
- owner_id: owner_id-in-path
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- shared_images: shared_images
Response Example
----------------
.. literalinclude:: samples/shared-images-list-response.json
:language: json

26
api-ref/source/v1/index.rst
View File

@ -1,26 +0,0 @@
..
Copyright 2010 OpenStack Foundation
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
:tocdepth: 3
=================================
Image Service API v1 (DEPRECATED)
=================================
.. rest_expand_all::
.. include:: images-images-v1.inc
.. include:: images-sharing-v1.inc

249
api-ref/source/v1/parameters.yaml
View File

@ -1,249 +0,0 @@
# variables in header
location:
description: |
A URI location for the image record.
format: uri
in: header
required: true
type: string
x-image-meta-container_format:
description: |
The image ``container_format`` property. (Optional when only reserving
an image.)
A container format defines the file format of the
file that contains the image and metadata about the actual VM.
For a VM image with a ``bare`` container format, the image is a
blob of unstructured data. You can set the container format to
one of these values:
- ``aki`` - Amazon kernel image.
- ``ami`` - Amazon machine image.
- ``ari`` - Amazon ramdisk image.
- ``bare`` - No container or metadata envelope for the image.
- ``docker`` - Docker tar archive of the container filesystem.
- ``ova`` - OVA container format.
- ``ovf`` - OVF container format.
in: header
required: true
type: enum
x-image-meta-disk_format:
description: |
The image ``disk_format`` property. (Optional when only reserving
an image.)
The disk format of a VM image is the format of
the underlying disk image. Virtual appliance vendors have
different formats for laying out the information contained in a VM
disk image. You can set the disk format for your image to one of
these values:
- ``aki`` - An Amazon kernel image.
- ``ami`` - An Amazon machine image.
- ``ari`` - An Amazon ramdisk image.
- ``iso`` - An archive format for the data contents of an optical
disc, such as CDROM.
- ``qcow2``- Supported by the QEMU emulator that can expand dynamically
and supports Copy on Write.
- ``raw`` - Unstructured disk image format.
- ``vhd`` - VHD disk format, a common disk format used by hypervisors
from VMWare, Xen, Microsoft, VirtualBox, and others.
- ``vdi`` - Supported by VirtualBox VM monitor and the QEMU emulator.
- ``vmdk`` - A common disk format that supported by many hypervisors.
in: header
required: true
type: enum
x-image-meta-name:
description: |
The image ``name`` property. (Optional when only reserving
an image.)
An image name is not required to be unique, though of course it will be
easier to tell your images apart if you give them distinct descriptive
names. Names are limited to 255 chars.
in: header
required: true
type: string
x-openstack-request-id:
description: |
Request identifier passed through by the various OpenStack services.
in: header
required: false
type: string
# variables in path
image_id-in-path:
description: |
Image ID stored through the image API. Typically a UUID.
in: path
required: true
type: string
member_id-in-path:
description: |
The tenant ID of the tenant with whom an image is shared, that is, the
tenant ID of the image member.
in: path
required: true
type: string
owner_id-in-path:
description: |
Owner ID, which is the tenant ID.
in: path
required: true
type: string
# variables in query
changes-since:
description: |
Filters the image list to those images that have changed since a time
stamp value.
in: query
required: false
type: string
container_format-in-query:
description: |
Filters the image list by a container format. A
valid value is ``aki``, ``ami``, ``ari``, ``bare``, ``docker``,
``ova``, or ``ovf``.
in: query
required: false
type: string
disk_format-in-query:
description: |
Filters the image list by a disk format. A valid
value is ``aki``, ``ami``, ``ari``, ``iso``, ``qcow2``, ``raw``,
``vhd``, ``vdi``, or ``vmdk``.
in: query
required: false
type: string
name-in-query:
description: |
Filters the image list by an image name, in string format.
in: query
required: false
type: string
size_max:
description: |
Filters the image list by a maximum image size, in bytes.
in: query
required: false
type: int
size_min:
description: |
Filters the image list by a minimum image size, in bytes.
in: query
required: false
type: int
status-in-query:
description: |
Filters the image list by a status. A valid value is ``queued``,
``saving``, ``active``, ``killed``, ``deleted``, or ``pending_delete``.
in: query
required: false
type: string
# variables in body
can_share:
description: |
Indicates whether the image member whose tenant ID is ``member_id``
is authorized to share the image. If the member can share the image,
this value is ``true``. Otherwise, this value is ``false``.
in: body
required: false
type: boolean
createImage:
description: |
The virtual machine image data. Do not include this if you are only
reserving an image.
in: body
required: true
type: binary
image-object:
description: |
A JSON representation of the image. Includes all metadata fields.
in: body
required: true
type: object
images-detail-list:
description: |
A list of image objects.
Each object contains the following fields:
- ``checksum`` - The MD5 checksum of the image data.
- ``container_format`` - The container format.
- ``created_at`` - Timestamp of image record creation.
- ``deleted`` - ``true`` if the image is deleted, ``false``
otherwise.
- ``deleted_at`` - Timestamp when the image went to ``deleted``
status.
- ``disk_format`` - The disk format.
- ``id`` - The image ID, typically a UUID.
- ``is_public`` - This is ``true`` if the image is public,
``false`` otherwise.
- ``name`` - The name of the image.
- ``owner`` - The image owner, usually the tenant_id.
- ``properties`` - A dict of user-specified key:value pairs (that
is, custom image metadata).
- ``protected`` - A boolean value that must be ``false`` or the
image cannot be deleted. Default value is ``false``.
- ``size`` - The size of the stored image data in bytes.
- ``status`` - The image status.
- ``updated_at`` - Timestamp of when the image record was most
recently modified.
- ``virtual_size`` - The size of the virtual machine image (the
virtual disk itself, not the containing package, if any) in bytes.
in: body
required: true
type: array
images-list:
description: |
A list of image objects in a sparse representation.
Each object contains the following fields:
- ``checksum`` - The MD5 checksum of the image data.
- ``container_format`` - The container format.
- ``disk_format`` - The disk format.
- ``id`` - The image ID, typically a UUID.
- ``name`` - The name of the image.
- ``size`` - The size of the image in bytes.
in: body
required: true
type: array
member_id:
description: |
The tenant ID of the tenant with whom an image is shared, that is, the
tenant ID of the image member.
in: body
required: true
type: string
memberships:
description: |
List of image member objects.
in: body
required: true
type: array
next:
description: |
Show the next item in the list.
format: uri
in: body
required: false
type: string
previous:
description: |
Show the previous item in the list.
format: uri
in: body
required: false
type: string
shared_images:
description: |
A list of objects, each of which contains an ``image_id`` and a
``can_share`` field. If all the members of the image are such that
``can_share`` is ``true`` for each member, then the ``can_share``
value in this object will be ``true``, otherwise it will be ``false``.
in: body
required: true
type: array

4
api-ref/source/v1/samples/image-member-add-request.json
View File

@ -1,4 +0,0 @@
{
"member_id": "eb5d80bd5f1e49f1818988148c70eabf",
"can_share": false
}

12
api-ref/source/v1/samples/image-members-add-request.json
View File

@ -1,12 +0,0 @@
{
"memberships": [
{
"member_id": "eb5d80bd5f1e49f1818988148c70eabf",
"can_share": false
},
{
"member_id": "8f450f44647d4080a0e7ca505057b5ca",
"can_share": false
}
]
}

11
api-ref/source/v1/samples/image-memberships-list-response.json
View File

@ -1,11 +0,0 @@
{
"memberships": [
{
"member_id": "tenant1",
"can_share": false
},
{
"...": "..."
}
]
}

25
api-ref/source/v1/samples/image-update-response.json
View File

@ -1,25 +0,0 @@
{
"image": {
"checksum": "eb9139e4942121f22bbc2afc0400b2a4",
"container_format": "bare",
"created_at": "2016-03-15T15:09:07.000000",
"deleted": false,
"deleted_at": null,
"disk_format": "vmdk",
"id": "1086fa65-8c63-4081-9a0a-ddf7e88e485b",
"is_public": false,
"min_disk": 22,
"min_ram": 11,
"name": "Silas Marner",
"owner": "c60b1d57c5034e0d86902aedf8c49be0",
"properties": {
"foo": "bar",
"qe_status": "approved"
},
"protected": false,
"size": 25165824,
"status": "active",
"updated_at": "2016-05-10T21:14:04.000000",
"virtual_size": null
}
}

22
api-ref/source/v1/samples/images-create-reserve-response.json
View File

@ -1,22 +0,0 @@
{
"image": {
"checksum": null,
"container_format": null,
"created_at": "2016-05-10T21:35:15.000000",
"deleted": false,
"deleted_at": null,
"disk_format": null,
"id": "6b3ecfca-d445-4946-a8d1-c4938352b251",
"is_public": false,
"min_disk": 0,
"min_ram": 0,
"name": null,
"owner": "c60b1d57c5034e0d86902aedf8c49be0",
"properties": {},
"protected": false,
"size": 0,
"status": "queued",
"updated_at": "2016-05-10T21:35:15.000000",
"virtual_size": null
}
}

22
api-ref/source/v1/samples/images-create-with-data-response.json
View File

@ -1,22 +0,0 @@
{
"image": {
"checksum": "7b1b10607acc1319506185e7227ca30d",
"container_format": "bare",
"created_at": "2016-05-10T21:41:41.000000",
"deleted": false,
"deleted_at": null,
"disk_format": "raw",
"id": "de2f2211-3ac7-4260-9142-41db0ecfb425",
"is_public": false,
"min_disk": 0,
"min_ram": 0,
"name": "Fake Image",
"owner": "c60b1d57c5034e0d86902aedf8c49be0",
"properties": {},
"protected": false,
"size": 3908,
"status": "active",
"updated_at": "2016-05-10T21:41:41.000000",
"virtual_size": null
}
}

30
api-ref/source/v1/samples/images-list-details-response.json
View File

@ -1,30 +0,0 @@
{
"images": [
{
"checksum": "eb9139e4942121f22bbc2afc0400b2a4",
"container_format": "bare",
"created_at": "2016-03-15T15:09:07.000000",
"deleted": false,
"deleted_at": null,
"disk_format": "vmdk",
"id": "1086fa65-8c63-4081-9a0a-ddf7e88e485b",
"is_public": false,
"min_disk": 22,
"min_ram": 11,
"name": "Silas Marner",
"owner": "c60b1d57c5034e0d86902aedf8c49be0",
"properties": {
"foo": "bar",
"qe_status": "approved"
},
"protected": false,
"size": 25165824,
"status": "active",
"updated_at": "2016-05-10T21:14:04.000000",
"virtual_size": null
},
{
"...": "..."
}
]
}

15
api-ref/source/v1/samples/images-list-response.json
View File

@ -1,15 +0,0 @@
{
"images": [
{
"checksum": "eb9139e4942121f22bbc2afc0400b2a4",
"container_format": "ovf",
"disk_format": "vmdk",
"id": "008cc101-c3ee-40dd-8477-cd8d99dcbf3d",
"name": "Harry",
"size": 25165824
},
{
"...": "..."
}
]
}

15
api-ref/source/v1/samples/shared-images-list-response.json
View File

@ -1,15 +0,0 @@
{
"shared_images": [
{
"can_share": false,
"image_id": "008cc101-c3ee-40dd-8477-cd8d99dcbf3d"
},
{
"can_share": true,
"image_id": "de2f2211-3ac7-4260-9142-41db0ecfb425"
},
{
"...": "..."
}
]
}

5
api-ref/source/versions/index.rst
View File

@ -24,6 +24,11 @@ Image Service Versions
Version History
***************
**Rocky changes**
- version 1.1 is DELETED
- version 1.0 is DELETED
**Queens changes**
- version 2.6 is CURRENT

20
api-ref/source/versions/samples/image-versions-response.json
View File

@ -69,26 +69,6 @@
}
],
"status": "SUPPORTED"
},
{
"id": "v1.1",
"links": [
{
"href": "http://glance.openstack.example.org/v1/",
"rel": "self"
}
],
"status": "DEPRECATED"
},
{
"id": "v1.0",
"links": [
{
"href": "http://glance.openstack.example.org/v1/",
"rel": "self"
}
],
"status": "DEPRECATED"
}
]
}