openstack/glance
Code Issues Proposed changes

Tidy up API docs

Browse Source 
* Add bit about images api vs glance
* Explain how to send auth token
* Prepend '/v1' to example URIs

Related to bp glance-folsom-docs-cleanup

Change-Id: I2c3b568e463f62033268573f50f2d8a74d053965
This commit is contained in:
Brian Waldon 2012-08-22 19:55:27 -07:00
parent 4c038b0d85
commit 7a0d2eb6cd
1 changed files with 69 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
doc/source/glanceapi.rst
View File

@ -17,52 +17,58 @@
Using Glance's Public APIs Using Glance's Public APIs
========================== ==========================
Glance has a RESTful API that exposes both metadata about registered virtual Glance fully implements versions 1.0, 1.1 and 2.0 of the OpenStack Images API.
machine images and the image data itself. The Images API specification is developed alongside Glance, but is not
considered part of the Glance project.
A host that runs the ``bin/glance-api`` service is said to be a *Glance API Authentication
Server*. --------------
Assume there is a Glance API server running at the URL Glance depends on Keystone and the OpenStack Identity API to handle
``http://glance.example.com``. authentication of clients. You must obtain an authentication token from
Keystone using and send it along with all API requests to Glance through
the ``X-Auth-Token`` header. Glance will communicate back to Keystone to
verify the token validity and obtain your identity credentials.
Let's walk through how a user might request information from this server. Using v1.X
----------
Requesting a List of Public VM Images For the purpose of examples, assume there is a Glance API server running
------------------------------------- at the URL ``http://glance.example.com`` on the default port 80.
We want to see a list of available virtual machine images that the Glance List Available Images
server knows about. *********************
We issue a ``GET`` request to ``http://glance.example.com/images/`` to retrieve We want to see a list of available images that the authenticated user has
this list of available *public* images. The data is returned as a JSON-encoded access to. This includes images owned by the user, images shared with the user
and public images.
We issue a ``GET`` request to ``http://glance.example.com/v1/images`` to
retrieve this list of available images. The data is returned as a JSON-encoded
mapping in the following format:: mapping in the following format::
{'images': [ {'images': [
{'uri': 'http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9', {'uri': 'http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
'name': 'Ubuntu 10.04 Plain', 'name': 'Ubuntu 10.04 Plain',
'disk_format': 'vhd', 'disk_format': 'vhd',
'container_format': 'ovf', 'container_format': 'ovf',
'size': '5368709120'} 'size': '5368709120'}
...]} ...]}
.. note::
All images returned from the above `GET` request are *public* images List Available Images in More Detail
************************************
We want to see a more detailed list of available images that the authenticated
user has access to. This includes images owned by the user, images shared with
the user and public images.
Requesting Detailed Metadata on Public VM Images We issue a ``GET`` request to ``http://glance.example.com/v1/images/detail`` to
------------------------------------------------ retrieve this list of available images. The data is returned as a
We want to see more detailed information on available virtual machine images
that the Glance server knows about.
We issue a ``GET`` request to ``http://glance.example.com/images/detail`` to
retrieve this list of available *public* images. The data is returned as a
JSON-encoded mapping in the following format:: JSON-encoded mapping in the following format::
{'images': [ {'images': [
{'uri': 'http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9', {'uri': 'http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
'name': 'Ubuntu 10.04 Plain 5GB', 'name': 'Ubuntu 10.04 Plain 5GB',
'disk_format': 'vhd', 'disk_format': 'vhd',
'container_format': 'ovf', 'container_format': 'ovf',
@ -81,8 +87,6 @@ JSON-encoded mapping in the following format::
.. note:: .. note::
All images returned from the above `GET` request are *public* images
All timestamps returned are in UTC All timestamps returned are in UTC
The `updated_at` timestamp is the timestamp when an image's metadata The `updated_at` timestamp is the timestamp when an image's metadata
@ -106,10 +110,10 @@ JSON-encoded mapping in the following format::
The `owner` field is a string which may either be null or which will The `owner` field is a string which may either be null or which will
indicate the owner of the image indicate the owner of the image
Filtering Images Returned via ``GET /images`` and ``GET /images/detail`` Filtering Images Lists
------------------------------------------------------------------------ **********************
Both the ``GET /images`` and ``GET /images/detail`` requests take query Both the ``GET /v1/images`` and ``GET /v1/images/detail`` requests take query
parameters that serve to filter the returned list of images. The following parameters that serve to filter the returned list of images. The following
list details these query parameters. list details these query parameters.
@ -156,30 +160,29 @@ These two resources also accept sort parameters:
Results will be sorted in the direction ``DIR``. Accepted values are ``asc`` Results will be sorted in the direction ``DIR``. Accepted values are ``asc``
for ascending or ``desc`` (default) for descending. for ascending or ``desc`` (default) for descending.
Retrieve Image Metadata
Requesting Detailed Metadata on a Specific Image ***********************
------------------------------------------------
We want to see detailed information for a specific virtual machine image We want to see detailed information for a specific virtual machine image
that the Glance server knows about. that the Glance server knows about.
We have queried the Glance server for a list of public images and the We have queried the Glance server for a list of images and the
data returned includes the `uri` field for each available image. This data returned includes the `uri` field for each available image. This
`uri` field value contains the exact location needed to get the metadata `uri` field value contains the exact location needed to get the metadata
for a specific image. for a specific image.
Continuing the example from above, in order to get metadata about the Continuing the example from above, in order to get metadata about the
first public image returned, we can issue a ``HEAD`` request to the Glance first image returned, we can issue a ``HEAD`` request to the Glance
server for the image's URI. server for the image's URI.
We issue a ``HEAD`` request to We issue a ``HEAD`` request to
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9`` to ``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9`` to
retrieve complete metadata for that image. The metadata is returned as a retrieve complete metadata for that image. The metadata is returned as a
set of HTTP headers that begin with the prefix ``x-image-meta-``. The set of HTTP headers that begin with the prefix ``x-image-meta-``. The
following shows an example of the HTTP headers returned from the above following shows an example of the HTTP headers returned from the above
``HEAD`` request:: ``HEAD`` request::
x-image-meta-uri http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9 x-image-meta-uri http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
x-image-meta-name Ubuntu 10.04 Plain 5GB x-image-meta-name Ubuntu 10.04 Plain 5GB
x-image-meta-disk_format vhd x-image-meta-disk_format vhd
x-image-meta-container_format ovf x-image-meta-container_format ovf
@ -218,23 +221,23 @@ following shows an example of the HTTP headers returned from the above
be null or which will indicate the owner of the image be null or which will indicate the owner of the image
Retrieving a Virtual Machine Image Retrieve Raw Image Data
---------------------------------- ***********************
We want to retrieve that actual raw data for a specific virtual machine image We want to retrieve that actual raw data for a specific virtual machine image
that the Glance server knows about. that the Glance server knows about.
We have queried the Glance server for a list of public images and the We have queried the Glance server for a list of images and the
data returned includes the `uri` field for each available image. This data returned includes the `uri` field for each available image. This
`uri` field value contains the exact location needed to get the metadata `uri` field value contains the exact location needed to get the metadata
for a specific image. for a specific image.
Continuing the example from above, in order to get metadata about the Continuing the example from above, in order to get metadata about the
first public image returned, we can issue a ``HEAD`` request to the Glance first image returned, we can issue a ``HEAD`` request to the Glance
server for the image's URI. server for the image's URI.
We issue a ``GET`` request to We issue a ``GET`` request to
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9`` to ``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9`` to
retrieve metadata for that image as well as the image itself encoded retrieve metadata for that image as well as the image itself encoded
into the response body. into the response body.
@ -242,7 +245,7 @@ The metadata is returned as a set of HTTP headers that begin with the
prefix ``x-image-meta-``. The following shows an example of the HTTP headers prefix ``x-image-meta-``. The following shows an example of the HTTP headers
returned from the above ``GET`` request:: returned from the above ``GET`` request::
x-image-meta-uri http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9 x-image-meta-uri http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
x-image-meta-name Ubuntu 10.04 Plain 5GB x-image-meta-name Ubuntu 10.04 Plain 5GB
x-image-meta-disk_format vhd x-image-meta-disk_format vhd
x-image-meta-container_format ovf x-image-meta-container_format ovf
@ -288,8 +291,8 @@ returned from the above ``GET`` request::
`application/octet-stream`. `application/octet-stream`.
Adding a New Virtual Machine Image Add a New Image
---------------------------------- ***************
We have created a new virtual machine image in some way (created a We have created a new virtual machine image in some way (created a
"golden image" or snapshotted/backed up an existing image) and we "golden image" or snapshotted/backed up an existing image) and we
@ -303,15 +306,14 @@ Assuming, like in the examples above, that a Glance API server is running
at ``glance.example.com``, we issue a ``POST`` request to add an image to at ``glance.example.com``, we issue a ``POST`` request to add an image to
Glance:: Glance::
POST http://glance.example.com/images/ POST http://glance.example.com/v1/images
The metadata about the image is sent to Glance in HTTP headers. The body The metadata about the image is sent to Glance in HTTP headers. The body
of the HTTP request to the Glance API will be the MIME-encoded disk of the HTTP request to the Glance API will be the MIME-encoded disk
image data. image data.
Adding Image Metadata in HTTP Headers **Image Metadata in HTTP Headers**
*************************************
Glance will view as image metadata any HTTP header that it receives in a Glance will view as image metadata any HTTP header that it receives in a
``POST`` request where the header key is prefixed with the strings ``POST`` request where the header key is prefixed with the strings
@ -396,7 +398,7 @@ The list of metadata headers that Glance accepts are listed below.
a public image, meaning that any user may view its metadata and may read a public image, meaning that any user may view its metadata and may read
the disk image from Glance. the disk image from Glance.
When not present, the image is assumed to be *not public* and specific to When not present, the image is assumed to be *not public* and owned by
a user. a user.
* ``x-image-meta-min-ram`` * ``x-image-meta-min-ram``
@ -444,8 +446,8 @@ The list of metadata headers that Glance accepts are listed below.
of image properties. of image properties.
Updating an Image Update an Image
***************** ***************
Glance will view as image metadata any HTTP header that it receives in a Glance will view as image metadata any HTTP header that it receives in a
``PUT`` request where the header key is prefixed with the strings ``PUT`` request where the header key is prefixed with the strings
@ -462,8 +464,8 @@ headers.
See more about image statuses here: :doc:`Image Statuses <statuses>` See more about image statuses here: :doc:`Image Statuses <statuses>`
Requesting Image Memberships List Image Memberships
---------------------------- **********************
We want to see a list of the other system tenants (or users, if We want to see a list of the other system tenants (or users, if
"owner_is_tenant" is False) that may access a given virtual machine image that "owner_is_tenant" is False) that may access a given virtual machine image that
@ -471,9 +473,9 @@ the Glance server knows about. We take the `uri` field of the image data,
append ``/members`` to it, and issue a ``GET`` request on the resulting URL. append ``/members`` to it, and issue a ``GET`` request on the resulting URL.
Continuing from the example above, in order to get the memberships for the Continuing from the example above, in order to get the memberships for the
first public image returned, we can issue a ``GET`` request to the Glance first image returned, we can issue a ``GET`` request to the Glance
server for server for
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9/members`` ``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members``
. What we will get back is JSON data such as the following:: . What we will get back is JSON data such as the following::
{'members': [ {'members': [
@ -486,11 +488,11 @@ that tenant is authorized to further share the image, the `can_share` field is
`true`. `true`.
Requesting Shared Images List Shared Images
------------------------ ******************
We want to see a list of images which are shared with a given tenant. We issue We want to see a list of images which are shared with a given tenant. We issue
a ``GET`` request to ``http://glance.example.com/shared-images/tenant1``. We a ``GET`` request to ``http://glance.example.com/v1/shared-images/tenant1``. We
will get back JSON data such as the following:: will get back JSON data such as the following::
{'shared_images': [ {'shared_images': [
@ -503,12 +505,12 @@ The `image_id` field identifies an image shared with the tenant named by
`can_share` field is `true`. `can_share` field is `true`.
Adding a Member to an Image Add a Member to an Image
--------------------------- ************************
We want to authorize a tenant to access a private image. We issue a ``PUT`` We want to authorize a tenant to access a private image. We issue a ``PUT``
request to request to
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9/members/tenant1`` ``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members/tenant1``
. With no body, this will add the membership to the image, leaving existing . With no body, this will add the membership to the image, leaving existing
memberships unmodified and defaulting new memberships to have `can_share` memberships unmodified and defaulting new memberships to have `can_share`
set to `false`. We may also optionally attach a body of the following form:: set to `false`. We may also optionally attach a body of the following form::
@ -522,20 +524,20 @@ If such a body is provided, both existing and new memberships will have
will return a 204 ("No Content") status code. will return a 204 ("No Content") status code.
Removing a Member from an Image Remove a Member from an Image
------------------------------- *****************************
We want to revoke a tenant's right to access a private image. We issue a We want to revoke a tenant's right to access a private image. We issue a
``DELETE`` request to ``http://glance.example.com/images/1/members/tenant1``. ``DELETE`` request to ``http://glance.example.com/v1/images/1/members/tenant1``.
This query will return a 204 ("No Content") status code. This query will return a 204 ("No Content") status code.
Replacing a Membership List for an Image Replace a Membership List for an Image
---------------------------------------- **************************************
The full membership list for a given image may be replaced. We issue a ``PUT`` The full membership list for a given image may be replaced. We issue a ``PUT``
request to request to
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9/members`` ``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members``
with a body of the following form:: with a body of the following form::
{'memberships': [ {'memberships': [