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
This commit is contained in:
bria4010 2016-05-03 17:27:58 -04:00
parent aab90f4727
commit ee1b6dce3c
20 changed files with 1342 additions and 0 deletions

224
api-ref/source/conf.py Normal file

@ -0,0 +1,224 @@
# -*- coding: utf-8 -*-
#
# 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.
#
# glance api-ref build config file, copied from:
# nova documentation build configuration file, created by
# sphinx-quickstart on Sat May 1 15:17:47 2010.
#
# This file is execfile()d with the current directory set to
# its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os
import subprocess
import sys
import warnings
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('../../'))
sys.path.insert(0, os.path.abspath('../'))
sys.path.insert(0, os.path.abspath('./'))
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'os_api_ref',
'oslosphinx',
]
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Image Service API Reference'
copyright = u'2010-present, OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
from glance.version import version_info
# The full version, including alpha/beta/rc tags.
release = version_info.release_string()
# The short X.Y version.
version = version_info.version_string()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# The reST default role (used for this markup: `text`) to use
# for all documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = False
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for man page output ----------------------------------------------
# Grouping the document tree for man pages.
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
# -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
git_cmd = [
"git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", "-n1"
]
try:
html_last_updated_fmt = subprocess.Popen(
git_cmd, stdout=subprocess.PIPE).communicate()[0]
except Exception:
warnings.warn('Cannot get last updated time from git repository. '
'Not setting "html_last_updated_fmt".')
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_use_modindex = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'glancedoc'
# -- Options for LaTeX output -------------------------------------------------
# The paper size ('letter' or 'a4').
# latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
# latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index', 'Glance.tex', u'OpenStack Image Service API Documentation',
u'OpenStack Foundation', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# Additional stuff for the LaTeX preamble.
# latex_preamble = ''
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_use_modindex = True

26
api-ref/source/index.rst Normal file

@ -0,0 +1,26 @@
..
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.
==================
Image Service APIs
==================
.. toctree::
:maxdepth: 2
versions/index
v1/index
.. v2/index

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

@ -0,0 +1,150 @@
.. -*- 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 overriden 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

@ -0,0 +1,26 @@
..
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 (SUPPORTED)
================================
.. rest_expand_all::
.. include:: images-images-v1.inc
.. include:: images-sharing-v1.inc

@ -0,0 +1,249 @@
# 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

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

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

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

@ -0,0 +1,25 @@
{
"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
}
}

@ -0,0 +1,22 @@
{
"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
}
}

@ -0,0 +1,22 @@
{
"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
}
}

@ -0,0 +1,30 @@
{
"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
},
{
"...": "..."
}
]
}

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

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

@ -0,0 +1,22 @@
..
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: 2
======================
Image Service Versions
======================
.. rest_expand_all::
.. include:: versions.inc

@ -0,0 +1,74 @@
{
"versions": [
{
"status": "CURRENT",
"id": "v2.4",
"links": [
{
"href": "http://glance.openstack.org:9292/v2/",
"rel": "self"
}
]
},
{
"status": "SUPPORTED",
"id": "v2.3",
"links": [
{
"href": "http://glance.openstack.org:9292/v2/",
"rel": "self"
}
]
},
{
"status": "SUPPORTED",
"id": "v2.2",
"links": [
{
"href": "http://glance.openstack.org:9292/v2/",
"rel": "self"
}
]
},
{
"status": "SUPPORTED",
"id": "v2.1",
"links": [
{
"href": "http://glance.openstack.org:9292/v2/",
"rel": "self"
}
]
},
{
"status": "SUPPORTED",
"id": "v2.0",
"links": [
{
"href": "http://glance.openstack.org:9292/v2/",
"rel": "self"
}
]
},
{
"status": "SUPPORTED",
"id": "v1.1",
"links": [
{
"href": "http://glance.openstack.org:9292/v1/",
"rel": "self"
}
]
},
{
"status": "SUPPORTED",
"id": "v1.0",
"links": [
{
"href": "http://glance.openstack.org:9292/v1/",
"rel": "self"
}
]
}
]
}

@ -0,0 +1,56 @@
.. -*- rst -*-
API versions
************
List API versions
~~~~~~~~~~~~~~~~~
.. rest_method:: GET /versions
Lists information about all Image service API versions supported by this
deployment, including the URIs.
Normal response codes: 200
Request
-------
There are no request parameters.
Response Example
----------------
.. literalinclude:: samples/image-versions-response.json
:language: json
List API versions
~~~~~~~~~~~~~~~~~
.. rest_method:: GET /
Lists information about all Image service API versions supported by this
deployment, including the URIs.
Normal response codes: 300
Request
-------
There are no request parameters.
Response Example
----------------
.. literalinclude:: samples/image-versions-response.json
:language: json

@ -33,5 +33,6 @@ xattr>=0.4 # MIT
python-swiftclient>=2.2.0 # Apache-2.0
# Documentation
os-api-ref>=0.1.0 # Apache-2.0
oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0
reno>=1.6.2 # Apache2

14
tox.ini

@ -73,6 +73,20 @@ commands =
[testenv:docs]
commands = python setup.py build_sphinx
[testenv:api-ref]
# This environment is called from CI scripts to test and publish
# the API Ref to developer.openstack.org.
#
# NOTE(sdague): this target does not use constraints because
# upstream infra does not yet support it. Once that's fixed, we can
# drop the install_command.
whitelist_externals = bash
rm
install_command = pip install -U --force-reinstall {opts} {packages}
commands =
rm -rf api-ref/build
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
[testenv:bandit]
commands = bandit -c bandit.yaml -r glance -n5 -p gate