openstack-attic/image-api
Code Issues Proposed changes

Add documentation for Images API v2 image sharing

Browse Source 
Image sharing was added to the Images API v2 for the Grizzly release
but was not documented in the API Reference or API Quick Reference.
This commit adds the missing documentation to the Image Service API
v2 Reference.

Also corrects image update example in Appendix A.

Change-Id: I263918ee81c8d7442cb6ef7764231b396a68b1ff
Partial-Bug: #1227801
This commit is contained in:
Brian Rosmaita 2013-09-22 15:30:52 +00:00
parent 7b631a9383
commit 0507f6d44d
3 changed files with 343 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -1,6 +1,6 @@
# OS generated files #
######################
.DS_Store?
.DS_Store
# Built documentation #
#######################

BIN
openstack-image-service-api/src/.DS_Store vendored
View File

Binary file not shown.

379
openstack-image-service-api/src/markdown/image-api-v2.0.md
View File

@ -1,12 +1,14 @@
#OpenStack Image Service API v2 Reference
##General API Information
The Image Service API v2 provides methods for storing and retrieving disk and server images.
###Versioning
#General API Information
##Versioning
**Two-part versioning scheme**
The Image Service API v2 follows the lead of the v1 API and use a major version and a minor version. For example, 'v2.3' would break down to major version 2 and minor version 3
The Image Service API v2 follows the lead of the v1 API and use a major version and a minor version. For example, 'v2.3' would break down to major version 2 and minor version 3.
**Backwards-compatibility**
@ -14,7 +16,7 @@ The Image Service API v2 follows the lead of the v1 API and use a major version
The interface will not be reduced with subsequent minor version releases, it will only be expanded. For example, everything in v2.1 will be available in v2.2.
###HTTP Response Status Codes
##HTTP Response Status Codes
The following HTTP status codes are all valid responses:
@ -30,19 +32,19 @@ The following HTTP status codes are all valid responses:
Responses that don't have a 200-level response code are not guaranteed to have a body. If a response does happen to return a body, it is not part of this spec and cannot be depended upon.
###Authentication and Authorization
##Authentication and Authorization
This spec does not govern how one might authenticate or authorize clients of the v2 Images API. Implementors are free to decide how to identify clients and what authorization rules to apply.
Note that the HTTP status codes 401 and 403 are included in this specification as valid response codes.
###Request/Response Content Format
##Request/Response Content Format
The v2 Images API primarily accepts and serves JSON-encoded data. In certain cases it also accepts and serves binary image data. Most requests that send JSON-encoded data must have the proper media type in their Content-Type header: 'application/json'. HTTP PATCH requests must use the patch media type defined for the entity they intend to modify. Requests that upload image data should use the media type 'application/octet-stream'.
Each call only responds in one format, so clients should not worry about sending an Accept header. It will be ignored. Assume a response will be formatted as 'application/json' unless otherwise stated in this spec.
###Image Entities
##Image Entities
An image entity is represented by a JSON-encoded data structure and its raw binary data.
@ -52,15 +54,15 @@ An image is always guaranteed to have the following attributes: id, status, visi
A client may set arbitrarily-named attributes on their images if the `image` json-schema allows it. These user-defined attributes will appear like any other image attributes. See [documentation](http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.4) of the additionalProperties json-schema attribute.
###JSON Schemas
##JSON Schemas
The necessary [json-schema](http://tools.ietf.org/html/draft-zyp-json-schema-03) documents will be provided at predictable URIs. A consumer should be able to validate server responses and client requests based on the published schemas. The schemas contained in this document are only examples and should not be used to validate your requests. A client should **always** fetch schemas from the server.
##Metadata API
#Metadata API
The following calls allow you to create, modify, and delete image metadata records. For binary image data, see [Binary Data API](#binary-data-api).
###Get Images Schema
##Get Images Schema
**GET /v2/schemas/images**
@ -112,7 +114,7 @@ Response body will contain a json-schema document representing an `images` entit
]
}
###Get Image Schema
##Get Image Schema
**GET /v2/schemas/image**
@ -149,7 +151,7 @@ Response body will contain a json-schema document representing an `image`. For e
}
###Create an Image
##Create an Image
**POST /v2/images**
@ -177,7 +179,7 @@ Successful HTTP response will be 201 Created with a Location header containing t
}
###Update an Image
##Update an Image
**PATCH /v2/images/\<IMAGE_ID\>**
@ -218,7 +220,7 @@ Similarly, to remove a property such as "login-user" from an image, use the foll
See Appendix B for more details about the 'application/openstack-images-v2.0-json-patch' media type.
###Add an Image Tag
##Add an Image Tag
**PUT /v2/images/\<IMAGE_ID\>/tags/\<TAG\>**
@ -231,7 +233,7 @@ An image can only be tagged once with a specific string. Multiple attempts to ta
An HTTP status of 204 will be returned.
###Delete an Image Tag
##Delete an Image Tag
**DELETE /v2/images/\<IMAGE_ID\>/tags/\<TAG\>**
@ -240,8 +242,7 @@ The tag you want to delete should be encoded into the request URI. For example,
An HTTP status of 204 will be returned. Subsequent attempts to delete the tag will result in a 404.
###List All Images
##List All Images
**GET /v2/images**
@ -317,7 +318,7 @@ The 'size_min' and 'size_max' query parameters can be used to do greater-than an
The results of this operation can be ordered using the 'sort_key' and 'sort_dir' parameters. The API uses the natural sorting of whatever image attribute is provided as the 'sort_key'. All image attributes can be used as the sort_key (except tags and link attributes). The sort_dir parameter indicates in which direction to sort. Acceptable values are 'asc' (ascending) and 'desc' (descending). Defaults values for sort_key and sort_dir are 'created_at' and 'desc'.
###Get an Image
##Get an Image
**GET /v2/images/\<IMAGE_ID\>**
@ -341,7 +342,7 @@ Response body will be a single image entity. Using **GET /v2/image/da3b75d9-3f4a
}
###Delete an Image
##Delete an Image
**DELETE /v2/images/\<IMAGE_ID\>**
@ -352,11 +353,313 @@ Images with the 'protected' attribute set to true (boolean) cannot be deleted an
The response will be empty with an HTTP 204 status code.
## Binary Data API
##Image Sharing
The OpenStack Image Service API v2 allows users to share images with each other.
Let the "producer" be a tenant who owns image 71c675ab-d94f-49cd-a114-e12490b328d9, and let the "consumer" be a tenant who would like to boot an instance from that image.
The producer can share the image with the consumer by making the consumer a **member** of that image.
To prevent spamming, the consumer must **accept** the image before it will be included in the consumer's image list.
The consumer can still boot from the image, however, if the consumer knows the image ID.
In summary:
* The image producer may add or remove image members, but may not modify the member status of an image member.
* An image consumer may change his or her member status, but may not add or remove him or herself as an image member.
* A consumer may boot an instance from a shared image regardless of whether he/she has "accepted" the image.
###Producer-Consumer Communication
No provision is made in this API for producer-consumer communication.
All such communication must be done independently of the API.
An example workflow is:
1. The producer posts the availability of specific images on a public website.
1. A potential consumer provides the producer with his/her tenant ID and email address.
1. The producer uses the Images v2 API to share the image with the consumer.
1. The producer notifies the consumer via email that the image has been shared and what its UUID is.
1. If the consumer wishes the image to appear in his/her image list, the Images v2 API is used to change the image status to `accepted`.
1. If the consumer subsequently wishes to hide the image, the Images v2 API may be used to change the member status to `rejected`.
If the consumer wishes to hide the image, but is open to the possibility of being reminded by the producer that the image is available, the Images v2 API may be used to change the member status to `pending`.
Note that as far as this API is concerned, the member status has only two effects:
* If the member status is *not* `accepted`, the image will not appear in the consumer's default image list.
* The consumer's image list may be filtered by status to see shared images in the various member statuses.
For example, the consumer can discover images that have been shared with him or her by filtering on `visibility=shared&member_status=pending`.
###Image Sharing Schemas
JSON schema documents are provided at the URIs listed below.
Recall that the schemas contained in this document are only examples and should not be used to validate your requests.
####Get Image Member Schema
**GET /v2/schemas/member**
Request body ignored.
Response body will contain a json-schema document representing an image `member` entity.
The response from the API should be considered authoritative.
The schema is reproduced here solely for your convenience:
{
"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"
},
"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"
},
"schema": {
"type": "string"
}
}
}
####Get Image Members Schema
**GET /v2/schemas/members**
Request body ignored.
Response body will contain a json-schema document representing an image `members` entity (a container of `member` entities).
The response from the API should be considered authoritative.
The schema is reproduced here solely for your convenience:
{
"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"
},
"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"
},
"schema": {
"type": "string"
}
}
},
"type": "array"
},
"schema": {
"type": "string"
}
},
"links": [
{
"href": "{schema}",
"rel": "describedby"
}
]
}
###Image Producer Calls
The following calls are germane to a user who wishes to act as a producer of shared images.
####Create an Image Member
**POST /v2/images/\<IMAGE_ID\>/members**
The request body must be JSON in the following format:
{
"member": "<MEMBER_ID>"
}
where the MEMBER_ID is the ID of the tenant with whom the image is to be shared.
The member status of a newly created image member is `pending`.
If the user making the call is not the image owner, the response is HTTP status code 404.
The response will conform to the JSON schema available at **/v2/schemas/member**, for example,
{
"created_at": "2013-09-19T20:36:53Z",
"image_id": "71c675ab-d94f-49cd-a114-e12490b328d9",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-09-19T20:36:53Z"
}
####Delete an Image Member
**DELETE /v2/images/\<IMAGE_ID\>/members/\<MEMBER_ID\>**
A successful response is 204 (No Content).
The call will return HTTP status code 404 if MEMBER_ID is not an image member of the specified image.
The call will return HTTP status code 404 if the user making the call is not the image owner.
###Image Consumer Calls
The following calls pertain to a user who wishes to act as a consumer of shared images.
####Update an Image Member
**PUT /v2/images/\<IMAGE_ID\>/members/\<MEMBER_ID\>**
The body of the request is a JSON object specifying the member status to which the image member should be updated:
{
"status": "<STATUS_VALUE>"
}
where STATUS_VALUE is one of { `pending`, `accepted`, or `rejected` }.
The response will conform to the JSON schema available at **/v2/schemas/member**, for example,
{
"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"
}
If the call is made by the image owner, the response is HTTP status code 403 (Forbidden).
If the call is made by a user who is not the image owner and whose tenant ID is not the same as the MEMBER_ID, the response is HTTP status code 404.
####Image Member Status Values
There are three image member status values:
* `pending`: When a member is created, its status is set to `pending`.
The image is not visible in the member's image-list, but the member can still boot instances from the image.
* `accepted`: When a member's status is `accepted`, the image is visible in the member's image-list.
The member can boot instances from the image.
* `rejected`: When a member's status is `rejected`, the member has decided that he or she does not wish to see the image.
The image is not visible in the member's image-list, but the member can still boot instances from the image.
###Calls for Both Producers and Consumers
These calls are applicable to users acting either as producers or consumers of shared images.
####List Image Members
**GET /v2/images/\<IMAGE_ID\>/members**
The response will conform to the JSON schema available at **/v2/schemas/members**, for example,
{
"members": [
{
"created_at": "2013-09-20T19:16:53Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "818baf9e073fd04fa78989447062e04a",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-09-20T19:16:53Z"
},
{
"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:22:19Z"
}
],
"schema": "/v2/schemas/members"
}
If the call is made by a user with whom the image has been shared, the member-list will contain *only* the information for that user.
For example, if the call is made by tenant 8989447062e04a818baf9e073fd04fa7, the response will be:
{
"members": [
{
"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:22:19Z"
}
],
"schema": "/v2/schemas/members"
}
If the call is made by a user with whom the image is *not* shared, the response will be a 404.
####List Shared Images
Shared images are listed as part of the normal image list call.
In this section we emphasize some useful filtering options.
* `visibility=shared`: show only images shared with me where my member status is 'accepted'
* `visibility=shared&member_status=accepted`: same as above
* `visibility=shared&member_status=pending`: show only images shared with me where my member status is 'pending'
* `visibility=shared&member_status=rejected`: show only images shared with me where my member status is 'rejected'
* `visibility=shared&member_status=all`: show all images shared with me regardless of my member status
* `owner=<OWNER_ID>`: show only images shared with me by the user whose tenant ID is OWNER_ID
# Binary Data API
The following API calls are used to upload and download raw image data. For image metadata, see [Metadata API](#metadata-api).
###Store Image File
##Store Image File
**PUT /v2/images/\<IMAGE_ID\>/file**
@ -366,7 +669,7 @@ Request Content-Type must be 'application/octet-stream'. Complete contents of re
Response status will be 204.
###Get Image File
##Get Image File
**GET /v2/images/\<IMAGE_ID\>/file**
@ -378,15 +681,15 @@ The [Content-MD5](http://www.ietf.org/rfc/rfc1864.txt) header will contain an MD
If no image data has been stored, an HTTP status of 204 will be returned.
##Appendix A: cURL Examples
#Appendix A: cURL Examples
This section is intended to provide a series of commands a typical client of the API might use to create and modify an image.
These commands assume the implementation of the v2 Images API is using the OpenStack Identity Service for authentication and authorization. The X-Auth-Token header is used to communicate the authentication token provided by that separate identity service.
The strings $OS_IMAGE_URL and $OS_AUTH_TOKEN represent variables defined in the client's environment. $OS_IMAGE_URL is the full path to your image service endpoint, i.e. 'http://localhost:9292'. $OS_AUTH_TOKEN represents an auth token generated by the OpenStack Identity Service, i.e. '6583fb17c27b48b4b4a6033fe9cc0fe0'.
The strings `$OS_IMAGE_URL` and `$OS_AUTH_TOKEN` represent variables defined in the client's environment. `$OS_IMAGE_URL` is the full path to your image service endpoint, for example, `http://localhost:9292`. `$OS_AUTH_TOKEN` represents an auth token generated by the OpenStack Identity Service, for example, `6583fb17c27b48b4b4a6033fe9cc0fe0`.
###Create an Image
##Create an Image
```
% curl -i -X POST -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/json" \
@ -416,12 +719,12 @@ Date: Tue, 14 Aug 2012 00:46:48 GMT
}
```
###Update the Image
##Update the Image
```
% curl -i -X PUT -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"login_user": "root"}' \
% curl -i -X PATCH -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/openstack-images-v2.0-json-patch"
-d '[{"add": "/login-user", "value": "root"}]' \
$OS_IMAGE_URL/v2/images/7b97f37c-899d-44e8-aaa0-543edbc4eaad
```
@ -447,7 +750,7 @@ Date: Tue, 14 Aug 2012 00:46:50 GMT
}
```
###Upload Binary Image Data
##Upload Binary Image Data
```
% curl -i -X PUT -H "X-Auth-Token: $OS_AUTH_TOKEN" \
@ -464,7 +767,7 @@ Content-Length: 0
Date: Tue, 14 Aug 2012 00:46:59 GMT
```
###Download Binary Image Data
##Download Binary Image Data
```
% curl -i -X GET -H "X-Auth-Token: $OS_AUTH_TOKEN" \
@ -481,7 +784,7 @@ Date: Thu, 14 Aug 2012 00:47:10 GMT
```
###Delete Image
##Delete Image
```
% curl -i -X DELETE -H "X-Auth-Token: $OS_AUTH_TOKEN" \
@ -494,15 +797,15 @@ Content-Length: 0
Date: Tue, 14 Aug 2012 00:47:12 GMT
```
##Appendix B: HTTP PATCH media types
#Appendix B: HTTP PATCH media types
###Overview
##Overview
The HTTP PATCH request must provide a media type for the server to determine how the patch should be applied to an image resource. An unsupported media type will result in an HTTP error response with the 415 status code. For image resources, the only supported media type for patch requests is 'application/openstack-images-v2.0-json-patch'.
The 'application/openstack-images-v2.0-json-patch' media type is intended to provide a useful and compatible subset of the functionality defined in the standard ['application/json-patch' media type](http://tools.ietf.org/html/draft-ietf-appsawg-json-patch).
###Restricted JSON Pointers
##Restricted JSON Pointers
The 'application/openstack-images-v2.0-json-patch' media type defined in this appendix adopts a restricted form of [JSON-Pointers](http://tools.ietf.org/html/draft-pbryan-zyp-json-pointer). A restricted JSON pointer is a [Unicode](http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-03#ref-Unicode) string containing a sequence of exactly one reference token, prefixed by a '/' (%x2F) character.
@ -542,11 +845,13 @@ the following restricted JSON pointers evaluate to the accompanying values:
"/tags" ["ping", "pong"]
"/~0~1.ssh~1" "present"
###Operations
##Operations
The 'application/openstack-images-v2.0-json-patch' media type supports a subset of the operations defined in the 'application/json-patch' media type. The operation to perform is expressed in a member of the operation object. The name of the operation member is one of: "add", "remove", "replace".
The member value is a string containing a restricted JSON pointer value that references the location within the target image to perform the operation. It is an error condition if an operation object contains no recognized operation member or more than one operation
The member value is a string containing a restricted JSON pointer value that references the location within the target image to perform the operation. It is an error condition if an operation object contains no recognized operation member or more than one operation.
The payload for a PATCH request must be a *list* of json objects, each of which adheres to one of the formats described below.
* add