f46438ab1c
Goal is to maintain API specs in the specs repo for each project and to eliminate the image-api repo. Splits up original v2 API document into multiple files. Change-Id: I7b6fbb1ee4a9a2e04395a7aa942d9ebdb011cc85
4.3 KiB
General Image API v2.x information
The Image Service API v2 enables you to store and retrieve disk and server images.
Versioning
Two-part versioning scheme
The Image Service API v2 mimics API v1 and uses a major version and a minor version. For example, v2.3 is major version 2 and minor version 3.
Backwards-compatibility
Minor version releases expand and do not reduce the interface. For example, everything in v2.1 is available in v2.2.
Property protections
The Images API v2.2 enables a cloud provider to employ property protections, an optional feature whereby CRUD protections are applied to image properties.
Thus, in particular deployments, non-admin users might not be able to view, update, or delete some image properties.
Additionally, non-admin users might be forced to follow a particular naming convention when creating custom image properties.
It is left to the cloud provider to communicate policies concerning property protections to users.
HTTP response status codes
The following HTTP status codes are all valid responses:
- 200 - generic successful response, expect a body
- 201 - entity created, expect a body and a Location header
- 204 - successful response without body
- 301 - redirection
- 400 - invalid request (syntax, value, etc)
- 401 - unauthenticated client
- 403 - authenticated client unable to perform action
- 409 - that action is impossible due to some (possibly permanent) circumstance
- 415 - unsupported media type
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
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 401 and 403 status codes are included in this specification as valid response codes.
Request and response content format
The Images Service API v2 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 is ignored. The response is formatted as 'application/json' unless otherwise stated in this spec.
Image entities
An image entity is represented by a JSON-encoded data structure and its raw binary data.
An image entity has an identifier (ID) that is guaranteed to be unique within the endpoint to which it belongs. The ID is used as a token in request URIs to interact with that specific image.
An image is always guaranteed to have the following attributes: id,
status, visibility, protected, tags, created_at, file and self. The
other attributes defined in the image schema below are
guaranteed to be defined, but is only returned with an image entity if
they have been explicitly set.
A client may set arbitrarily-named attributes on their images if the
image json-schema allows it. These user-defined attributes
appear like any other image attributes. See documentation
of the additionalProperties json-schema attribute.
JSON schemas
The necessary json-schema documents are 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.
Property Protections
Version 2.2 of the Images API acknowledges the ability of a cloud provider to employ property protections. Thus, there may be image properties that will not appear in the list images response for non-admin users.