From c028c2d23e3f32703f502e8919654df83f94e179 Mon Sep 17 00:00:00 2001 From: bria4010 Date: Wed, 22 Jun 2016 14:04:32 -0400 Subject: [PATCH] WADL to RST migration (part 2 - images) 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 --- api-ref/source/v2/images-data.inc | 132 ++++ api-ref/source/v2/images-images-v2.inc | 645 ++++++++++++++++++ api-ref/source/v2/images-parameters.yaml | 587 ++++++++++++++++ api-ref/source/v2/images-schemas.inc | 138 ++++ api-ref/source/v2/images-sharing-v2.inc | 360 ++++++++++ api-ref/source/v2/images-tags.inc | 52 ++ api-ref/source/v2/index.rst | 5 + .../v2/samples/image-create-request.json | 6 + .../v2/samples/image-create-response.json | 22 + .../image-details-deactivate-response.json | 21 + .../samples/image-member-create-request.json | 3 + .../samples/image-member-create-response.json | 8 + .../image-member-details-response.json | 8 + .../samples/image-member-update-request.json | 3 + .../samples/image-member-update-response.json | 8 + .../samples/image-members-list-response.json | 21 + .../v2/samples/image-show-response.json | 21 + .../v2/samples/image-update-request.json | 15 + .../v2/samples/image-update-response.json | 23 + .../v2/samples/images-list-response.json | 48 ++ .../schemas-image-member-show-response.json | 34 + .../schemas-image-members-list-response.json | 51 ++ .../samples/schemas-image-show-response.json | 216 ++++++ .../samples/schemas-images-list-response.json | 247 +++++++ 24 files changed, 2674 insertions(+) create mode 100644 api-ref/source/v2/images-data.inc create mode 100644 api-ref/source/v2/images-images-v2.inc create mode 100644 api-ref/source/v2/images-parameters.yaml create mode 100644 api-ref/source/v2/images-schemas.inc create mode 100644 api-ref/source/v2/images-sharing-v2.inc create mode 100644 api-ref/source/v2/images-tags.inc create mode 100644 api-ref/source/v2/samples/image-create-request.json create mode 100644 api-ref/source/v2/samples/image-create-response.json create mode 100644 api-ref/source/v2/samples/image-details-deactivate-response.json create mode 100644 api-ref/source/v2/samples/image-member-create-request.json create mode 100644 api-ref/source/v2/samples/image-member-create-response.json create mode 100644 api-ref/source/v2/samples/image-member-details-response.json create mode 100644 api-ref/source/v2/samples/image-member-update-request.json create mode 100644 api-ref/source/v2/samples/image-member-update-response.json create mode 100644 api-ref/source/v2/samples/image-members-list-response.json create mode 100644 api-ref/source/v2/samples/image-show-response.json create mode 100644 api-ref/source/v2/samples/image-update-request.json create mode 100644 api-ref/source/v2/samples/image-update-response.json create mode 100644 api-ref/source/v2/samples/images-list-response.json create mode 100644 api-ref/source/v2/samples/schemas-image-member-show-response.json create mode 100644 api-ref/source/v2/samples/schemas-image-members-list-response.json create mode 100644 api-ref/source/v2/samples/schemas-image-show-response.json create mode 100644 api-ref/source/v2/samples/schemas-images-list-response.json diff --git a/api-ref/source/v2/images-data.inc b/api-ref/source/v2/images-data.inc new file mode 100644 index 0000000000..e3310ae9ee --- /dev/null +++ b/api-ref/source/v2/images-data.inc @@ -0,0 +1,132 @@ +.. -*- rst -*- + +Image data +********** + +Uploads and downloads raw image data. + +*These operations may be restricted to administrators. Consult your cloud +operator's documentation for details.* + + +Upload binary image data +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: PUT /v2/images/{image_id}/file + +Uploads binary image data. +*(Since Image API v2.0)* + +Set the ``Content-Type`` request header to ``application/octet-stream``. + +Example call: + +:: + + curl -i -X PUT -H "X-Auth-Token: $token" \ + -H "Content-Type: application/octet-stream" \ + -d @/home/glance/ubuntu-12.10.qcow2 \ + $image_url/v2/images/{image_id}/file + +**Preconditions** + +Before you can store binary image data, you must meet the following +preconditions: + +- The image must exist. + +- You must set the disk and container formats in the image. + +- The image status must be ``queued``. + +- Your image storage quota must be sufficient. + +- The size of the data that you want to store must not exceed the + size that the OpenStack Image service allows. + +**Synchronous Postconditions** + +- With correct permissions, you can see the image status as + ``active`` through API calls. + +- With correct access, you can see the stored data in the storage + system that the OpenStack Image Service manages. + +**Troubleshooting** + +- If you cannot store the data, either your request lacks required + information or you exceeded your allotted quota. Ensure that you + meet the preconditions and run the request again. If the request + fails again, review your API request. + +- The storage back ends for storing the data must have enough free + storage space to accommodate the size of the data. + +Normal response codes: 204 + +Error response codes: 400, 401, 403, 404, 409, 410, 413, 415, 503 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - Content-type: Content-Type-data + - image_id: image_id-in-path + + +Download binary image data +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/images/{image_id}/file + +Downloads binary image data. +*(Since Image API v2.0)* + +Example call: ``curl -i -X GET -H "X-Auth-Token: $token" +$image_url/v2/images/{image_id}/file`` + +The response body contains the raw binary data that represents the +actual virtual disk. The ``Content-Type`` header contains the +``application/octet-stream`` value. The ``Content-MD5`` header +contains an MD5 checksum of the image data. Use this checksum to +verify the integrity of the image data. + +**Preconditions** + +- The image must exist. + +**Synchronous Postconditions** + +- You can download the binary image data in your machine if the + image has image data. + +- If image data exists, the call returns the HTTP ``200`` response code. + +- If no image data exists, the call returns the HTTP ``204`` (No Content) + response code. + +- If no image record exists, the call returns the HTTP ``404`` response code. + +Normal response codes: 200, 204 + +Error response codes: 400, 403, 404 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + - Content-Range: Content-Range + + +Response +-------- +.. rest_parameters:: images-parameters.yaml + + - Content-Type: Content-Type-data-response + - Content-Md5: Content-Md5 + - Content-Length: Content-Length diff --git a/api-ref/source/v2/images-images-v2.inc b/api-ref/source/v2/images-images-v2.inc new file mode 100644 index 0000000000..1b95f793be --- /dev/null +++ b/api-ref/source/v2/images-images-v2.inc @@ -0,0 +1,645 @@ +.. -*- rst -*- + +Images +****** + +Creates, lists, shows, updates, deletes, and performs other operations on +images. + +General information +~~~~~~~~~~~~~~~~~~~ + +**Images** + +An *image* is represented by a JSON Object, that is, as a set of key:value +pairs. Some of these keys are *base properties* that are managed by the +Image service. The remainder are properties put on the image by the operator +or the image owner. + +Here's some important information about image properties: + +* The base properties are always included in the image representation. A + base property that doesn't have a value is displayed with its value set + to ``null`` (that is, the JSON null data type). + +* Additional properties, whose value is always a string data type, are + only included in the response if they have a value. + +* Since version 2.2, the Images API allows an operator to configure + *property protections*, by which the create, read, update, and delete + operations on specific image properties may be restricted to particular + user roles. Consult the documentation of your cloud operator for details. + +* Arguably the most important properties of an image are its *id*, which + uniquely identifies the image, its *status*, which indicates the current + situation of the image (which, in turn, indicates what you can do with the + image), and its *visibility*, which indicates who has access to the image. + + +**Image status** + +The possible status values for images are presented in the following table. + +.. list-table:: + :header-rows: 1 + + * - Status + - Description + * - queued + - The Image service reserved an image ID for the image in the catalog + but did not yet upload any image data. + * - saving + - The Image service is is in the process of saving the the raw data for + the image into the backing store. + * - active + - The image is active and ready for consumption in the Image service. + * - killed + - An image data upload error occurred. + * - deleted + - The Image service retains information about the image but the image is + no longer available for use. + * - pending_delete + - Similar to the ``deleted`` status. An image in this state is not + recoverable. + * - deactivated + - The image data is not available for use. + +**Image visibility** + +The possible values for image visibility are presented in the following table. + +.. list-table:: + :header-rows: 1 + + * - Visibility + - Description + * - ``public`` + - Any tenant may access the image. Additionally, the image appears in + the default image list of all tenants. + * - ``private`` + - Only the tenant who owns the image, or any tenants the image has been + shared with, may access the image. Additionally, the image appears in + the default image list of the owning tenant. + + +Create an image +~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v2/images + +Creates a catalog record for an operating system disk image. +*(Since Image API v2.0)* + +The ``Location`` response header contains the URI for the image. +The response body contains the new image entity. + +Synchronous Postconditions + +- With correct permissions, you can see the image status as + ``queued`` through API calls. + +Normal response codes: 201 + +Error response codes: 400, 401, 403, 409, 413, 415 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - container_format: container_format-in-request + - disk_format: disk_format-in-request + - id: id-in-request + - min_disk: min_disk-in-request + - min_ram: min_ram-in-request + - name: name-in-request + - protected: protected-in-request + - tags: tags-in-request + - visibility: visibility-in-request + +Additionally, you may include additional properties specified as key:value +pairs, where the value must be a string data type. Keys and values are limited +to 255 chars in length. Available key names may be limited by the cloud's +property protection configuration. + +Request Example +--------------- + +.. literalinclude:: samples/image-create-request.json + :language: json + +Response Parameters +------------------- + +.. rest_parameters:: images-parameters.yaml + + - Location: Location + - checksum: checksum + - container_format: container_format + - created_at: created_at + - disk_format: disk_format + - file: file + - id: id + - min_disk: min_disk + - min_ram: min_ram + - name: name + - owner: owner + - protected: protected + - schema: schema-image + - self: self + - size: size + - status: status + - tags: tags + - updated_at: updated_at + - virtual_size: virtual_size + - visibility: visibility + - direct_url: direct_url + - locations: locations + +The response may also include additional properties specified as key:value +pairs if additional properties were specified in the request. + +Response Example +---------------- + +.. literalinclude:: samples/image-create-response.json + :language: json + + +Show image details +~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/images/{image_id} + +Shows details for an image. +*(Since Image API v2.0)* + +The response body contains a single image entity. + +Preconditions + +- The image must exist. + +Normal response codes: 200 + +Error response codes: 400, 401, 403, 404 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + + +Response Parameters +------------------- + +.. rest_parameters:: images-parameters.yaml + + - checksum: checksum + - container_format: container_format + - created_at: created_at + - disk_format: disk_format + - file: file + - id: id + - min_disk: min_disk + - min_ram: min_ram + - name: name + - owner: owner + - protected: protected + - schema: schema-image + - self: self + - size: size + - status: status + - tags: tags + - updated_at: updated_at + - virtual_size: virtual_size + - visibility: visibility + - direct_url: direct_url + - locations: locations + +The response may also include additional properties specified as key:value +pairs if such properties have been added to the image by the owner or an +administrator. + +Response Example +---------------- + +.. literalinclude:: samples/image-show-response.json + :language: json + + +Show images +~~~~~~~~~~~ + +.. rest_method:: GET /v2/images + +Lists public virtual machine (VM) images. +*(Since Image API v2.0)* + +**Pagination** + +Returns a subset of the larger collection of images and a link that you can use +to get the next set of images. You should always check for the presence of a +``next`` link and use it as the URI in a subsequent HTTP GET request. You +should follow this pattern until a ``next`` link is no longer provided. + +The ``next`` link preserves any query parameters that you send in your initial +request. You can use the ``first`` link to jump back to the first page of the +collection. If you prefer to paginate through images manually, use the +``limit`` and ``marker`` parameters. + +**Query Filters** + +The list operation accepts query parameters to filter the response. + +A client can provide direct comparison filters by using most image attributes, +such as ``name=Ubuntu``, ``visibility=public``, and so on. + +To filter using image tags, use the filter ``tag`` (note the singular). To +filter on multiple tags, include each tag separately in the query. For +example, to find images with the tag **ready**, include ``tag=ready`` in your +query string. To find images tagged with **ready** and **approved**, include +``tag=ready&tag=approved`` in your query string. (Note that only images +containing *both* tags will be included in the response.) + +A client cannot use any ``link`` in the json-schema, such as self, file, or +schema, to filter the response. + +You can list VM images that have a status of ``active``, ``queued``, or +``saving``. + +**The** ``in`` **Operator** + +As a convenience, you may specify several values for any of the following +fields by using the ``in`` operator: + +* container_format +* disk_format +* id +* name +* status + +For most of these, usage is straight forward. For example, to list images +in queued or saving status, use: + +``GET /v2/images?status=in:saving,queued`` + +To find images in a particular list of image IDs, use: + +``GET /v2/images?id=in:3afb79c1-131a-4c38-a87c-bc4b801d14e6,2e011209-660f-44b5-baf2-2eb4babae53d`` + +Using the ``in`` operator with the ``name`` property of images can be a bit +trickier, depending upon how creatively you have named your images. The +general rule is that if an image name contains a comma (``,``), you must +enclose the entire name in quotation marks (``"``). As usual, you must URL +encode any characters that require it. + +For example, to find images named ``glass, darkly`` or ``share me``, you would +use the following filter specification: + +``GET v2/images?name=in:"glass,%20darkly",share%20me`` + +As with regular filtering by name, you must specify the complete name you are +looking for. Thus, for example, the query string ``name=in:glass,share`` will +only match images with the exact name ``glass`` or the exact name ``share``. +It will not find an image named ``glass, darkly`` or an image named ``share +me``. + +**Size Comparison Filters** + +You can use the ``size_min`` and ``size_max`` query parameters to filter images +that are greater than or less than the image size. The size, in bytes, is the +size of an image on disk. + +For example, to filter the container to include only images that are from 1 to +4 MB, set the ``size_min`` query parameter to ``1048576`` and the ``size_max`` +query parameter to ``4194304``. + +.. _v2-comparison-ops: + +**Time Comparison Filters** + +You can use a *comparison operator* along with the ``created_at`` or +``updated_at`` fields to filter your results. Specify the operator first, a +colon (``:``) as a separator, and then the time in `ISO 8601 Format +`_. Available comparison operators +are: + +.. list-table:: + :header-rows: 1 + + * - Operator + - Description + * - ``gt`` + - Return results more recent than the specified time. + * - ``gte`` + - Return any results matching the specified time and also any more recent + results. + * - ``eq`` + - Return any results matching the specified time exactly. + * - ``neq`` + - Return any results that do not match the specified time. + * - ``lt`` + - Return results older than the specified time. + * - ``lte`` + - Return any results matching the specified time and also any older + results. + +For example: + +.. code-block:: console + + GET v2/images?created_at=gt:2016-04-18T21:38:54Z + +**Sorting** + +You can use query parameters to sort the results of this operation. + +- ``sort_key``. Sorts by an image attribute. Sorts in the natural + sorting direction of the image attribute. + +- ``sort_dir``. Sorts in a sort direction. + +- ``sort``. Sorts by one or more sets of attribute and sort + direction combinations. If you omit the sort direction in a set, + the default is ``desc``. + +To sort the response, use the ``sort_key`` and ``sort_dir`` query +parameters: + +.. code-block:: console + + GET /v2/images?sort_key=name&sort_dir=asc&sort_key=status&sort_dir=desc + +Alternatively, specify the ``sort`` query parameter: + +.. code-block:: console + + GET /v2/images?sort=name:asc,status:desc + +.. note:: + Although this call has been available since verison 2.0 of this API, + it has been enhanced from release to release. The filtering and + sorting functionality and syntax described above apply to the most + recent release (Newton). Not everything described above will be + available in prior releases. + +Normal response codes: 200 + +Error response codes: 400, 401, 403 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - limit: limit + - marker: marker + - name: name-in-query + - owner: owner-in-query + - status: status-in-query + - tag: tag-in-query + - visibility: visibility-in-query + - member_status: member_status-in-query + - size_max: size_max + - size_min: size_min + - created_at: created_at-in-query + - updated_at: updated_at-in-query + - sort_dir: sort_dir + - sort_key: sort_key + - sort: sort + + +Response Parameters +------------------- + +.. rest_parameters:: images-parameters.yaml + + - images: images + - first: first + - next: next + - schema: schema-images + + + +Response Example +---------------- + +.. literalinclude:: samples/images-list-response.json + :language: json + + +.. _v2-image-update: + +Update an image +~~~~~~~~~~~~~~~ + +.. rest_method:: PATCH /v2/images/{image_id} + +Updates an image. +*(Since Image API v2.0)* + +Conceptually, you update an image record by patching the JSON representation of +the image, passing a request body conforming to one of the following media +types: + +- ``application/openstack-images-v2.0-json-patch`` *(deprecated)* +- ``application/openstack-images-v2.1-json-patch`` *(since Image API v2.1)* + +Attempting to make a PATCH call using some other media type will provoke a +response code of 415 (Unsupported media type). + +The ``application/openstack-images-v2.1-json-patch`` media type provides a +useful and compatible subset of the functionality defined in JavaScript Object +Notation (JSON) Patch `RFC6902 `_, which +defines the ``application/json-patch+json`` media type. + +.. note:: + The ``application/openstack-images-v2.0-json-patch`` media type is based on + draft 4 of the standard. Its use is deprecated. + +For information about the PATCH method and the available media types, see +`Image API v2 HTTP PATCH media types +`_. + +Attempting to modify some image properties will cause the entire request to +fail with a 403 (Forbidden) response code: + +- An attempt to modify any of the "base" image properties that are managed by + the Image Service. These are the properties specified as read only in the + :ref:`Image Schema `. + +- An attempt to create or modify image properties for which you do not have + permission to do so. This depends upon how property protections are + configured in the OpenStack cloud in which you are making the call. Consult + your cloud's documentation for details. + +Normal response codes: 200 + +Error response codes: 400, 401, 403, 404, 413, 415 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - Content-Type: Content-Type-patch + - image_id: image_id-in-path + +The request body must conform to the +``application/openstack-images-v2.1-json-patch`` media type definition (see +above). + + +Request Example +--------------- + +.. literalinclude:: samples/image-update-request.json + :language: json + + +Response Parameters +------------------- + +.. rest_parameters:: images-parameters.yaml + + - checksum: checksum + - container_format: container_format + - created_at: created_at + - disk_format: disk_format + - file: file + - id: id + - min_disk: min_disk + - min_ram: min_ram + - owner: owner + - name: name + - protected: protected + - schema: schema-image + - self: self + - size: size + - status: status + - tags: tags + - updated_at: updated_at + - visibility: visibility + - direct_url: direct_url + - locations: locations + + + +Response Example +---------------- + +.. literalinclude:: samples/image-update-response.json + :language: json + + +Delete an image +~~~~~~~~~~~~~~~ + +.. rest_method:: DELETE /v2/images/{image_id} + +(Since Image API v2.0) Deletes an image. + +You cannot delete images with the ``protected`` attribute set to +``true`` (boolean). + +Preconditions + +- You can delete an image in any status except ``deleted``. + +- The ``protected`` attribute of the image cannot be ``true``. + +- You have permission to perform image deletion under the configured image + deletion policy. + +Synchronous Postconditions + +- The response is empty and returns the HTTP ``204`` response code. + +- The API deletes the image from the images index. + +- If the image has associated binary image data in the storage backend, the + OpenStack Image service deletes the data. + +Normal response codes: 204 + +Error response codes: 400, 401, 403, 404, 409 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + + +Deactivate image +~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v2/images/{image_id}/actions/deactivate + +Deactivates an image. +*(Since Image API v2.3)* + +By default, this operation is restricted to administrators only. + +If you try to download a deactivated image, you will receive a 403 (Forbidden) +response code. Additionally, only administrative users can view image +locations for deactivated images. + +The deactivate operation returns an error if the image status is +not ``active`` or ``deactivated``. + +Preconditions + +- The image must exist. + +Normal response codes: 204 + +Error response codes: 400, 403, 404 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + + +Reactivate image +~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v2/images/{image_id}/actions/reactivate + +Reactivates an image. +*(Since Image API v2.3)* + +By default, this operation is restricted to administrators only. + +The reactivate operation returns an error if the image status is +not ``active`` or ``deactivated``. + +Preconditions + +- The image must exist. + +Normal response codes: 204 + +Error response codes: 400, 403, 404 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml new file mode 100644 index 0000000000..c6fab5bd09 --- /dev/null +++ b/api-ref/source/v2/images-parameters.yaml @@ -0,0 +1,587 @@ +# 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 + `_. + 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 `). + + The date and time stamp format is `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 + `). + + The date and time stamp format is `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 + `_: + + :: + + 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 + `. + 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 + `. 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 + `_: + + :: + + 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 diff --git a/api-ref/source/v2/images-schemas.inc b/api-ref/source/v2/images-schemas.inc new file mode 100644 index 0000000000..70315dc704 --- /dev/null +++ b/api-ref/source/v2/images-schemas.inc @@ -0,0 +1,138 @@ +.. -*- rst -*- + +.. note: You can get a 400 on a GET if you pass a request body + (see router.py) + +Image Schemas +************* + +Gets a JSON-schema document that represents the various entities talked +about by the Images v2 API. + +.. _images-schema: + +Show images schema +~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/schemas/images + +*(Since Images v2.0)* + +Shows a JSON schema document that represents an *images* entity. + +An images entity is a container of image entities. + +The following schema is solely an example. Consider only the +response to the API call as authoritative. + +Normal response codes: 200 + +Error response codes: 400, 401 + + +Request +------- + +This operation has no request parameters and does not accept a request body. + + +Response Example +---------------- + +.. literalinclude:: samples/schemas-images-list-response.json + :language: json + +.. _image-schema: + +Show image schema +~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/schemas/image + +*(Since Images v2.0)* + +Shows a JSON schema document that represents an *image* entity. + +The following schema is solely an example. Consider only the +response to the API call as authoritative. + +Normal response codes: 200 + +Error response codes: 400, 401 + + +Request +------- + +This operation has no request parameters and does not accept a request body. + + +Response Example +---------------- + +.. literalinclude:: samples/schemas-image-show-response.json + :language: json + +.. _image-members-schema: + +Show image members schema +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/schemas/members + +*(Since Images v2.1)* + +Shows a JSON schema document that represents an *image members* entity. + +An image members entity is a container of image member entities. + +The following schema is solely an example. Consider only the +response to the API call as authoritative. + +Normal response codes: 200 + +Error response codes: 400, 401 + + +Request +------- + +This operation has no request parameters and does not accept a request body. + + +Response Example +---------------- + +.. literalinclude:: samples/schemas-image-members-list-response.json + :language: json + +.. _image-member-schema: + +Show image member schema +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/schemas/member + +*(Since Images v2.1)* + +Shows a JSON schema document that represents an *image member* entity. + +The following schema is solely an example. Consider only the +response to the API call as authoritative. + +Normal response codes: 200 + +Error response codes: 400, 401 + + +Request +------- + +This operation has no request parameters and does not accept a request body. + + +Response Example +---------------- + +.. literalinclude:: samples/schemas-image-member-show-response.json + :language: json diff --git a/api-ref/source/v2/images-sharing-v2.inc b/api-ref/source/v2/images-sharing-v2.inc new file mode 100644 index 0000000000..58186fa28b --- /dev/null +++ b/api-ref/source/v2/images-sharing-v2.inc @@ -0,0 +1,360 @@ +.. -*- rst -*- + +Sharing +******* + +Images may be shared among projects by creating *members* on the image. The +following calls allow you to create, list, update, and delete image members. + +.. note:: + + An image member is an identifier for a consumer with whom the image is + shared. In most OpenStack clouds, where the value of the ``owner`` property + of an image is a project ID, the appropriate identifier to use for the + ``member_id`` is the consumer's project ID (also known as the "tenant ID"). + In these clouds, image sharing is project-to-project, and all the individual + users in the consuming project have access to the image. + + * Some deployments may choose instead to have the identifier of the user who + created the image as the value of the ``owner`` property. In such clouds, + the appropriate identifier to use for the ``member_id`` is the user ID of + the person with whom you want to share the image. In these clouds, image + sharing is user-to-user. + + * Note that you, as an image owner, do not have a choice about what value to + use for the ``member_id``. If, like most OpenStack clouds, your cloud + uses the tenant ID for the image ``owner``, sharing will not work if you + use a user ID as the ``member_id`` of an image (and vice-versa). + + * Please consult your cloud's local documentation for details. + +When an image is shared, the member is given immediate access to the image. +In order to prevent spamming other users' image lists, a shared image does not +appear in a member's image list until the member "accepts" the image. + +Only the image owner may create members. Only an image member may modify his +or her member status. + +.. TODO(rosmaita): update the following reference when the "narrative" API + docs have a final resting place + +For a conceptual overview of image sharing, including a suggested workflow, +please consult `Image API v2 Sharing`_. + +.. _Image API v2 Sharing: + http://specs.openstack.org/openstack/glance-specs/specs/api/v2/sharing-image-api-v2.html + + +Create image member +~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v2/images/{image_id}/members + +Adds a tenant ID as an image member. +*(Since Image API v2.1)* + + +Preconditions + +- The image must exist. + +- The image cannot be a public image. + +- You must be the owner of the image. + +Synchronous Postconditions + +- With correct permissions, you can see the member status of the + image member as ``pending`` through API calls. + +Troubleshooting + +- Even if you have correct permissions, if the ``visibility`` + attribute is set to ``public``, the request returns the HTTP + ``403`` response code. Ensure that you meet the preconditions and + run the request again. If the request fails again, review your + API request. + +- If the member is already a member for the image, the service + returns the ``Conflict (409)`` response code. If you meant to + specify a different member, run the request again. + + +Normal response codes: 200 + +Error response codes: 400, 401, 403, 404, 409, 413 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + - member: member_id + +Request Example +--------------- + +.. literalinclude:: samples/image-member-create-request.json + :language: json + + + +Response Parameters +------------------- + +.. rest_parameters:: images-parameters.yaml + + - created_at: created_at + - image_id: image_id-in-body + - member_id: member_id + - schema: schema-member + - status: member_status + - updated_at: updated_at + +Response Example +---------------- + +.. literalinclude:: samples/image-member-create-response.json + :language: json + + +Show image member details +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/images/{image_id}/members/{member_id} + +Shows image member details. +*(Since Image API v2.1)* + +Response body is a single image member entity. + +Preconditions + +- The image must exist. + +- You must be the owner or the member of the image who's referenced in the + call. + + +Normal response codes: 200 + +Error response codes: 400, 401, 404 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + - member_id: member_id-in-path + + +Response Parameters +------------------- + +.. rest_parameters:: images-parameters.yaml + + - created_at: created_at + - image_id: image_id-in-body + - member_id: member_id + - schema: schema-member + - status: member_status + - updated_at: updated_at + + +Response Example +---------------- + +.. literalinclude:: samples/image-member-details-response.json + :language: json + + +List image members +~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/images/{image_id}/members + +Lists the tenants that share this image. +*(Since Image API v2.1)* + +If the image owner makes this call, the complete member list is +returned. + +If a user who is an image member makes this call, the member list +contains only information for that user. + +If a user who is not an image member makes this call, the call +returns the HTTP ``404`` response code. + +Preconditions + +- The image must exist. + +- You must be the owner or a member of the image. + + +Normal response codes: 200 + +Error response codes: 400, 401, 404 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + + +Response Parameters +------------------- + +.. rest_parameters:: images-parameters.yaml + + - members: members + - schema: schema-members + + +Response Example +---------------- + +.. literalinclude:: samples/image-members-list-response.json + :language: json + + +Update image member +~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: PUT /v2/images/{image_id}/members/{member_id} + +Sets the status for an image member. +*(Since Image API v2.1)* + +This call allows an image member to change his or her *member status*. + +When an image is shared with you, you have immediate access to the image. What +updating your member status on the image does for you is that it affects +whether the image will appear in your image list response. + +- When an image is shared with you, your member_status is ``pending``. You + won't see the image unless you go looking for it, either by making a show + image detail request using the image's ID, or by making an image list call + specifically looking for a shared image in member status ``pending``. This + way, other users cannot "spam" your image list with images you may not want + to see. + +- If you want to see a particular shared image in your image list, then you + must use this call to change your member status on the image to ``accepted``. + +- The image owner can see what your member status is on an image, but the owner + *cannot* change the status. Only you (or an administrator) can do that. + +- There are three member status values: ``pending``, ``accepted``, and + ``rejected``. The ``pending`` and ``rejected`` statuses are functionally + identical. The difference is that ``pending`` indicates to the owner that + you haven't updated the image, so perhaps you aren't aware that it's been + shared with you. The ``rejected`` status indicates that you are aware that + the image exists and you specifically decided that you don't want to see it + in your image list response. + +For a more detailed discussion of image sharing, please consult `Image API v2 +Sharing`_. + +Preconditions + +- The image must exist. + +- You must be the member of the image referenced in the call. + +Synchronous Postconditions + +- If you update the member status to ``accepted`` and have the + correct permissions, you see the image in list images responses. + +- With correct permissions, you can make API calls to see the + updated member status of the image. + + +Normal response codes: 200 + +Error response codes: 400, 401, 404, 403 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + - member_id: member_id-in-path + - status: member_status + +Request Example +--------------- + +.. literalinclude:: samples/image-member-update-request.json + :language: json + + + +Response Parameters +------------------- + +.. rest_parameters:: images-parameters.yaml + + - created_at: created_at + - image_id: image_id-in-body + - member_id: member_id + - schema: schema-member + - status: member_status + - updated_at: updated_at + + +Response Example +---------------- + +.. literalinclude:: samples/image-member-update-response.json + :language: json + + +Delete image member +~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: DELETE /v2/images/{image_id}/members/{member_id} + +Deletes a tenant ID from the member list of an image. +*(Since Image API v2.1)* + +Preconditions + +- The image must exist. + +- You must be the owner of the image. + +Synchronous Postconditions + +- The API removes the member from the image members. + +Troubleshooting + +- Even if you have correct permissions, if you are not the owner of + the image or you specify an incorrect image ID or member ID, the + call returns the HTTP ``403`` or ``404`` response code. Ensure + that you meet the preconditions and run the request again. If the + request fails again, review your API request URI. + +Normal response codes: 204 + +Error response codes: 400, 401, 403, 404 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + - member_id: member_id-in-path diff --git a/api-ref/source/v2/images-tags.inc b/api-ref/source/v2/images-tags.inc new file mode 100644 index 0000000000..9affb62e2f --- /dev/null +++ b/api-ref/source/v2/images-tags.inc @@ -0,0 +1,52 @@ +.. -*- rst -*- + +Image tags +********** + +Adds and deletes image tags. + +Image tags may also be modfied by the :ref:`v2-image-update` call. + + +Add image tag +~~~~~~~~~~~~~ + +.. rest_method:: PUT /v2/images/{image_id}/tags/{tag} + +Adds a tag to an image. +*(Since Image API v2.0)* + +Normal response codes: 204 + +Error response codes: 400, 401, 403, 404, 413 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + - tag: tag-in-path + + +Delete image tag +~~~~~~~~~~~~~~~~ + +.. rest_method:: DELETE /v2/images/{image_id}/tags/{tag} + +Deletes a tag from an image. +*(Since Image API v2.0)* + +Normal response codes: 204 + +Error response codes: 400, 401, 403, 404 + + +Request +------- + +.. rest_parameters:: images-parameters.yaml + + - image_id: image_id-in-path + - tag: tag-in-path diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 37c1bf1caf..d9247475bd 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -22,5 +22,10 @@ Image Service API v2 (CURRENT) .. rest_expand_all:: +.. include:: images-images-v2.inc +.. include:: images-sharing-v2.inc +.. include:: images-tags.inc +.. include:: images-schemas.inc +.. include:: images-data.inc .. include:: tasks.inc .. include:: tasks-schemas.inc diff --git a/api-ref/source/v2/samples/image-create-request.json b/api-ref/source/v2/samples/image-create-request.json new file mode 100644 index 0000000000..bcb480b683 --- /dev/null +++ b/api-ref/source/v2/samples/image-create-request.json @@ -0,0 +1,6 @@ +{ + "container_format": "bare", + "disk_format": "raw", + "name": "Ubuntu", + "id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb" +} diff --git a/api-ref/source/v2/samples/image-create-response.json b/api-ref/source/v2/samples/image-create-response.json new file mode 100644 index 0000000000..dd2289ee20 --- /dev/null +++ b/api-ref/source/v2/samples/image-create-response.json @@ -0,0 +1,22 @@ +{ + "status": "queued", + "name": "Ubuntu", + "tags": [], + "container_format": "bare", + "created_at": "2015-11-29T22:21:42Z", + "size": null, + "disk_format": "raw", + "updated_at": "2015-11-29T22:21:42Z", + "visibility": "private", + "locations": [], + "self": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb", + "min_disk": 0, + "protected": false, + "id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb", + "file": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb/file", + "checksum": null, + "owner": "bab7d5c60cd041a0a36f7c4b6e1dd978", + "virtual_size": null, + "min_ram": 0, + "schema": "/v2/schemas/image" +} diff --git a/api-ref/source/v2/samples/image-details-deactivate-response.json b/api-ref/source/v2/samples/image-details-deactivate-response.json new file mode 100644 index 0000000000..43d41c3351 --- /dev/null +++ b/api-ref/source/v2/samples/image-details-deactivate-response.json @@ -0,0 +1,21 @@ +{ + "status": "deactivated", + "name": "cirros-0.3.2-x86_64-disk", + "tags": [], + "container_format": "bare", + "created_at": "2014-05-05T17:15:10Z", + "disk_format": "qcow2", + "updated_at": "2014-05-05T17:15:11Z", + "visibility": "public", + "self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27", + "min_disk": 0, + "protected": false, + "id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27", + "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file", + "checksum": "64d7c1cd2b6f60c92c14662941cb7913", + "owner": "5ef70662f8b34079a6eddb8da9d75fe8", + "size": 13167616, + "min_ram": 0, + "schema": "/v2/schemas/image", + "virtual_size": null +} diff --git a/api-ref/source/v2/samples/image-member-create-request.json b/api-ref/source/v2/samples/image-member-create-request.json new file mode 100644 index 0000000000..06ad8fe9ac --- /dev/null +++ b/api-ref/source/v2/samples/image-member-create-request.json @@ -0,0 +1,3 @@ +{ + "member": "8989447062e04a818baf9e073fd04fa7" +} diff --git a/api-ref/source/v2/samples/image-member-create-response.json b/api-ref/source/v2/samples/image-member-create-response.json new file mode 100644 index 0000000000..d6946dd931 --- /dev/null +++ b/api-ref/source/v2/samples/image-member-create-response.json @@ -0,0 +1,8 @@ +{ + "created_at": "2013-09-20T19:22:19Z", + "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6", + "member_id": "8989447062e04a818baf9e073fd04fa7", + "schema": "/v2/schemas/member", + "status": "pending", + "updated_at": "2013-09-20T19:25:31Z" +} diff --git a/api-ref/source/v2/samples/image-member-details-response.json b/api-ref/source/v2/samples/image-member-details-response.json new file mode 100644 index 0000000000..870417fbdb --- /dev/null +++ b/api-ref/source/v2/samples/image-member-details-response.json @@ -0,0 +1,8 @@ +{ + "status": "pending", + "created_at": "2013-11-26T07:21:21Z", + "updated_at": "2013-11-26T07:21:21Z", + "image_id": "0ae74cc5-5147-4239-9ce2-b0c580f7067e", + "member_id": "8989447062e04a818baf9e073fd04fa7", + "schema": "/v2/schemas/member" +} diff --git a/api-ref/source/v2/samples/image-member-update-request.json b/api-ref/source/v2/samples/image-member-update-request.json new file mode 100644 index 0000000000..4ec147f047 --- /dev/null +++ b/api-ref/source/v2/samples/image-member-update-request.json @@ -0,0 +1,3 @@ +{ + "status": "accepted" +} diff --git a/api-ref/source/v2/samples/image-member-update-response.json b/api-ref/source/v2/samples/image-member-update-response.json new file mode 100644 index 0000000000..75ed4bed2d --- /dev/null +++ b/api-ref/source/v2/samples/image-member-update-response.json @@ -0,0 +1,8 @@ +{ + "created_at": "2013-09-20T19:22:19Z", + "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6", + "member_id": "8989447062e04a818baf9e073fd04fa7", + "schema": "/v2/schemas/member", + "status": "accepted", + "updated_at": "2013-09-20T20:15:31Z" +} diff --git a/api-ref/source/v2/samples/image-members-list-response.json b/api-ref/source/v2/samples/image-members-list-response.json new file mode 100644 index 0000000000..3b55ad0f56 --- /dev/null +++ b/api-ref/source/v2/samples/image-members-list-response.json @@ -0,0 +1,21 @@ +{ + "members": [ + { + "created_at": "2013-10-07T17:58:03Z", + "image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe", + "member_id": "123456789", + "schema": "/v2/schemas/member", + "status": "pending", + "updated_at": "2013-10-07T17:58:03Z" + }, + { + "created_at": "2013-10-07T17:58:55Z", + "image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe", + "member_id": "987654321", + "schema": "/v2/schemas/member", + "status": "accepted", + "updated_at": "2013-10-08T12:08:55Z" + } + ], + "schema": "/v2/schemas/members" +} diff --git a/api-ref/source/v2/samples/image-show-response.json b/api-ref/source/v2/samples/image-show-response.json new file mode 100644 index 0000000000..07055355cb --- /dev/null +++ b/api-ref/source/v2/samples/image-show-response.json @@ -0,0 +1,21 @@ +{ + "status": "active", + "name": "cirros-0.3.2-x86_64-disk", + "tags": [], + "container_format": "bare", + "created_at": "2014-05-05T17:15:10Z", + "disk_format": "qcow2", + "updated_at": "2014-05-05T17:15:11Z", + "visibility": "public", + "self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27", + "min_disk": 0, + "protected": false, + "id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27", + "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file", + "checksum": "64d7c1cd2b6f60c92c14662941cb7913", + "owner": "5ef70662f8b34079a6eddb8da9d75fe8", + "size": 13167616, + "min_ram": 0, + "schema": "/v2/schemas/image", + "virtual_size": null +} diff --git a/api-ref/source/v2/samples/image-update-request.json b/api-ref/source/v2/samples/image-update-request.json new file mode 100644 index 0000000000..9bbc50b203 --- /dev/null +++ b/api-ref/source/v2/samples/image-update-request.json @@ -0,0 +1,15 @@ +[ + { + "op": "replace", + "path": "/name", + "value": "Fedora 17" + }, + { + "op": "replace", + "path": "/tags", + "value": [ + "fedora", + "beefy" + ] + } +] diff --git a/api-ref/source/v2/samples/image-update-response.json b/api-ref/source/v2/samples/image-update-response.json new file mode 100644 index 0000000000..2fdcdd90f1 --- /dev/null +++ b/api-ref/source/v2/samples/image-update-response.json @@ -0,0 +1,23 @@ +{ + "id": "da3b75d9-3f4a-40e7-8a2c-bfab23927dea", + "name": "Fedora 17", + "status": "active", + "visibility": "public", + "size": 2254249, + "checksum": "2cec138d7dae2aa59038ef8c9aec2390", + "tags": [ + "fedora", + "beefy" + ], + "created_at": "2012-08-10T19:23:50Z", + "updated_at": "2012-08-12T11:11:33Z", + "self": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea", + "file": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea/file", + "schema": "/v2/schemas/image", + "owner": null, + "min_ram": null, + "min_disk": null, + "disk_format": null, + "virtual_size": null, + "container_format": null +} diff --git a/api-ref/source/v2/samples/images-list-response.json b/api-ref/source/v2/samples/images-list-response.json new file mode 100644 index 0000000000..8e2097a091 --- /dev/null +++ b/api-ref/source/v2/samples/images-list-response.json @@ -0,0 +1,48 @@ +{ + "images": [ + { + "status": "active", + "name": "cirros-0.3.2-x86_64-disk", + "tags": [], + "container_format": "bare", + "created_at": "2014-11-07T17:07:06Z", + "disk_format": "qcow2", + "updated_at": "2014-11-07T17:19:09Z", + "visibility": "public", + "self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27", + "min_disk": 0, + "protected": false, + "id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27", + "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file", + "checksum": "64d7c1cd2b6f60c92c14662941cb7913", + "owner": "5ef70662f8b34079a6eddb8da9d75fe8", + "size": 13167616, + "min_ram": 0, + "schema": "/v2/schemas/image", + "virtual_size": null + }, + { + "status": "active", + "name": "F17-x86_64-cfntools", + "tags": [], + "container_format": "bare", + "created_at": "2014-10-30T08:23:39Z", + "disk_format": "qcow2", + "updated_at": "2014-11-03T16:40:10Z", + "visibility": "public", + "self": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c", + "min_disk": 0, + "protected": false, + "id": "781b3762-9469-4cec-b58d-3349e5de4e9c", + "file": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c/file", + "checksum": "afab0f79bac770d61d24b4d0560b5f70", + "owner": "5ef70662f8b34079a6eddb8da9d75fe8", + "size": 476704768, + "min_ram": 0, + "schema": "/v2/schemas/image", + "virtual_size": null + } + ], + "schema": "/v2/schemas/images", + "first": "/v2/images" +} diff --git a/api-ref/source/v2/samples/schemas-image-member-show-response.json b/api-ref/source/v2/samples/schemas-image-member-show-response.json new file mode 100644 index 0000000000..5ad359d7d6 --- /dev/null +++ b/api-ref/source/v2/samples/schemas-image-member-show-response.json @@ -0,0 +1,34 @@ +{ + "name": "member", + "properties": { + "created_at": { + "description": "Date and time of image member creation", + "type": "string" + }, + "image_id": { + "description": "An identifier for the image", + "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", + "type": "string" + }, + "member_id": { + "description": "An identifier for the image member (tenantId)", + "type": "string" + }, + "schema": { + "type": "string" + }, + "status": { + "description": "The status of this image member", + "enum": [ + "pending", + "accepted", + "rejected" + ], + "type": "string" + }, + "updated_at": { + "description": "Date and time of last modification of image member", + "type": "string" + } + } +} diff --git a/api-ref/source/v2/samples/schemas-image-members-list-response.json b/api-ref/source/v2/samples/schemas-image-members-list-response.json new file mode 100644 index 0000000000..56a160266d --- /dev/null +++ b/api-ref/source/v2/samples/schemas-image-members-list-response.json @@ -0,0 +1,51 @@ +{ + "links": [ + { + "href": "{schema}", + "rel": "describedby" + } + ], + "name": "members", + "properties": { + "members": { + "items": { + "name": "member", + "properties": { + "created_at": { + "description": "Date and time of image member creation", + "type": "string" + }, + "image_id": { + "description": "An identifier for the image", + "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", + "type": "string" + }, + "member_id": { + "description": "An identifier for the image member (tenantId)", + "type": "string" + }, + "schema": { + "type": "string" + }, + "status": { + "description": "The status of this image member", + "enum": [ + "pending", + "accepted", + "rejected" + ], + "type": "string" + }, + "updated_at": { + "description": "Date and time of last modification of image member", + "type": "string" + } + } + }, + "type": "array" + }, + "schema": { + "type": "string" + } + } +} diff --git a/api-ref/source/v2/samples/schemas-image-show-response.json b/api-ref/source/v2/samples/schemas-image-show-response.json new file mode 100644 index 0000000000..52279a8358 --- /dev/null +++ b/api-ref/source/v2/samples/schemas-image-show-response.json @@ -0,0 +1,216 @@ +{ + "additionalProperties": { + "type": "string" + }, + "links": [ + { + "href": "{self}", + "rel": "self" + }, + { + "href": "{file}", + "rel": "enclosure" + }, + { + "href": "{schema}", + "rel": "describedby" + } + ], + "name": "image", + "properties": { + "architecture": { + "description": "Operating system architecture as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html", + "is_base": false, + "type": "string" + }, + "checksum": { + "description": "md5 hash of image contents. (READ-ONLY)", + "maxLength": 32, + "type": [ + "null", + "string" + ] + }, + "container_format": { + "description": "Format of the container", + "enum": [ + null, + "ami", + "ari", + "aki", + "bare", + "ovf", + "ova" + ], + "type": [ + "null", + "string" + ] + }, + "created_at": { + "description": "Date and time of image registration (READ-ONLY)", + "type": "string" + }, + "direct_url": { + "description": "URL to access the image file kept in external store (READ-ONLY)", + "type": "string" + }, + "disk_format": { + "description": "Format of the disk", + "enum": [ + null, + "ami", + "ari", + "aki", + "vhd", + "vmdk", + "raw", + "qcow2", + "vdi", + "iso" + ], + "type": [ + "null", + "string" + ] + }, + "file": { + "description": "(READ-ONLY)", + "type": "string" + }, + "id": { + "description": "An identifier for the image", + "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", + "type": "string" + }, + "instance_uuid": { + "description": "ID of instance used to create this image.", + "is_base": false, + "type": "string" + }, + "kernel_id": { + "description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.", + "is_base": false, + "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", + "type": "string" + }, + "locations": { + "description": "A set of URLs to access the image file kept in external store", + "items": { + "properties": { + "metadata": { + "type": "object" + }, + "url": { + "maxLength": 255, + "type": "string" + } + }, + "required": [ + "url", + "metadata" + ], + "type": "object" + }, + "type": "array" + }, + "min_disk": { + "description": "Amount of disk space (in GB) required to boot image.", + "type": "integer" + }, + "min_ram": { + "description": "Amount of ram (in MB) required to boot image.", + "type": "integer" + }, + "name": { + "description": "Descriptive name for the image", + "maxLength": 255, + "type": [ + "null", + "string" + ] + }, + "os_distro": { + "description": "Common name of operating system distribution as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html", + "is_base": false, + "type": "string" + }, + "os_version": { + "description": "Operating system version as specified by the distributor", + "is_base": false, + "type": "string" + }, + "owner": { + "description": "Owner of the image", + "maxLength": 255, + "type": [ + "null", + "string" + ] + }, + "protected": { + "description": "If true, image will not be deletable.", + "type": "boolean" + }, + "ramdisk_id": { + "description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.", + "is_base": false, + "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", + "type": "string" + }, + "schema": { + "description": "(READ-ONLY)", + "type": "string" + }, + "self": { + "description": "(READ-ONLY)", + "type": "string" + }, + "size": { + "description": "Size of image file in bytes (READ-ONLY)", + "type": [ + "null", + "integer" + ] + }, + "status": { + "description": "Status of the image (READ-ONLY)", + "enum": [ + "queued", + "saving", + "active", + "killed", + "deleted", + "pending_delete" + ], + "type": "string" + }, + "tags": { + "description": "List of strings related to the image", + "items": { + "maxLength": 255, + "type": "string" + }, + "type": "array" + }, + "updated_at": { + "description": "Date and time of the last image modification (READ-ONLY)", + "type": "string" + }, + "virtual_size": { + "description": "Virtual size of image in bytes (READ-ONLY)", + "type": [ + "null", + "integer" + ] + }, + "visibility": { + "description": "Scope of image accessibility", + "enum": [ + "public", + "private" + ], + "type": "string" + } + } +} diff --git a/api-ref/source/v2/samples/schemas-images-list-response.json b/api-ref/source/v2/samples/schemas-images-list-response.json new file mode 100644 index 0000000000..2d148eb939 --- /dev/null +++ b/api-ref/source/v2/samples/schemas-images-list-response.json @@ -0,0 +1,247 @@ +{ + "links": [ + { + "href": "{first}", + "rel": "first" + }, + { + "href": "{next}", + "rel": "next" + }, + { + "href": "{schema}", + "rel": "describedby" + } + ], + "name": "images", + "properties": { + "first": { + "type": "string" + }, + "images": { + "items": { + "additionalProperties": { + "type": "string" + }, + "links": [ + { + "href": "{self}", + "rel": "self" + }, + { + "href": "{file}", + "rel": "enclosure" + }, + { + "href": "{schema}", + "rel": "describedby" + } + ], + "name": "image", + "properties": { + "architecture": { + "description": "Operating system architecture as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html", + "is_base": false, + "type": "string" + }, + "checksum": { + "description": "md5 hash of image contents. (READ-ONLY)", + "maxLength": 32, + "type": [ + "null", + "string" + ] + }, + "container_format": { + "description": "Format of the container", + "enum": [ + null, + "ami", + "ari", + "aki", + "bare", + "ovf", + "ova" + ], + "type": [ + "null", + "string" + ] + }, + "created_at": { + "description": "Date and time of image registration (READ-ONLY)", + "type": "string" + }, + "direct_url": { + "description": "URL to access the image file kept in external store (READ-ONLY)", + "type": "string" + }, + "disk_format": { + "description": "Format of the disk", + "enum": [ + null, + "ami", + "ari", + "aki", + "vhd", + "vmdk", + "raw", + "qcow2", + "vdi", + "iso" + ], + "type": [ + "null", + "string" + ] + }, + "file": { + "description": "(READ-ONLY)", + "type": "string" + }, + "id": { + "description": "An identifier for the image", + "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", + "type": "string" + }, + "instance_uuid": { + "description": "ID of instance used to create this image.", + "is_base": false, + "type": "string" + }, + "kernel_id": { + "description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.", + "is_base": false, + "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", + "type": "string" + }, + "locations": { + "description": "A set of URLs to access the image file kept in external store", + "items": { + "properties": { + "metadata": { + "type": "object" + }, + "url": { + "maxLength": 255, + "type": "string" + } + }, + "required": [ + "url", + "metadata" + ], + "type": "object" + }, + "type": "array" + }, + "min_disk": { + "description": "Amount of disk space (in GB) required to boot image.", + "type": "integer" + }, + "min_ram": { + "description": "Amount of ram (in MB) required to boot image.", + "type": "integer" + }, + "name": { + "description": "Descriptive name for the image", + "maxLength": 255, + "type": [ + "null", + "string" + ] + }, + "os_distro": { + "description": "Common name of operating system distribution as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html", + "is_base": false, + "type": "string" + }, + "os_version": { + "description": "Operating system version as specified by the distributor", + "is_base": false, + "type": "string" + }, + "owner": { + "description": "Owner of the image", + "maxLength": 255, + "type": [ + "null", + "string" + ] + }, + "protected": { + "description": "If true, image will not be deletable.", + "type": "boolean" + }, + "ramdisk_id": { + "description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.", + "is_base": false, + "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", + "type": "string" + }, + "schema": { + "description": "(READ-ONLY)", + "type": "string" + }, + "self": { + "description": "(READ-ONLY)", + "type": "string" + }, + "size": { + "description": "Size of image file in bytes (READ-ONLY)", + "type": [ + "null", + "integer" + ] + }, + "status": { + "description": "Status of the image (READ-ONLY)", + "enum": [ + "queued", + "saving", + "active", + "killed", + "deleted", + "pending_delete" + ], + "type": "string" + }, + "tags": { + "description": "List of strings related to the image", + "items": { + "maxLength": 255, + "type": "string" + }, + "type": "array" + }, + "updated_at": { + "description": "Date and time of the last image modification (READ-ONLY)", + "type": "string" + }, + "virtual_size": { + "description": "Virtual size of image in bytes (READ-ONLY)", + "type": [ + "null", + "integer" + ] + }, + "visibility": { + "description": "Scope of image accessibility", + "enum": [ + "public", + "private" + ], + "type": "string" + } + } + }, + "type": "array" + }, + "next": { + "type": "string" + }, + "schema": { + "type": "string" + } + } +}