298 lines
9.1 KiB
ReStructuredText
298 lines
9.1 KiB
ReStructuredText
Image Metadata API calls
|
|
========================
|
|
|
|
The following calls allow you to create, modify, and delete image
|
|
metadata records.
|
|
|
|
Create image
|
|
------------
|
|
|
|
**POST /v2/images**
|
|
|
|
Request body must be JSON-encoded and conform to the ``image`` JSON
|
|
schema. For example:
|
|
|
|
::
|
|
|
|
{
|
|
"id": "e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
|
|
"name": "Ubuntu 12.10",
|
|
"tags": ["ubuntu", "quantal"]
|
|
}
|
|
|
|
Successful HTTP response is 201 Created with a Location header
|
|
containing the newly-created URI for the image. The response body shows
|
|
the created ``image`` entity. For example:
|
|
|
|
::
|
|
|
|
{
|
|
"id": "e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
|
|
"name": "Ubuntu 12.10",
|
|
"status": "queued",
|
|
"visibility": "public",
|
|
"tags": ["ubuntu", "quantal"],
|
|
"created_at": "2012-08-11T17:15:52Z",
|
|
"updated_at": "2012-08-11T17:15:52Z",
|
|
"self": "/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
|
|
"file": "/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/file",
|
|
"schema": "/v2/schemas/image"
|
|
}
|
|
|
|
.. _image-update:
|
|
|
|
Update an image
|
|
---------------
|
|
|
|
**PATCH /v2/images/{image\_id}**
|
|
|
|
Request body must conform to the
|
|
'application/openstack-images-v2.1-json-patch' media type, documented in
|
|
Appendix B. Using **PATCH
|
|
/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd** as an example:
|
|
|
|
::
|
|
|
|
[
|
|
{"op": "replace", "path": "/name", "value": "Fedora 17"},
|
|
{"op": "replace", "path": "/tags", "value": ["fedora", "beefy"]}
|
|
]
|
|
|
|
The response body shows the updated ``image`` entity. For example:
|
|
|
|
::
|
|
|
|
{
|
|
"id": "e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
|
|
"name": "Fedora 17",
|
|
"status": "queued",
|
|
"visibility": "public",
|
|
"tags": ["fedora", "beefy"],
|
|
"created_at": "2012-08-11T17:15:52Z",
|
|
"updated_at": "2012-08-11T17:15:52Z",
|
|
"self": "/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd",
|
|
"file": "/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/file",
|
|
"schema": "/v2/schemas/image"
|
|
}
|
|
|
|
The PATCH method can also be used to add or remove image properties. To
|
|
add a custom user-defined property such as "login-user" to an image, use
|
|
the following example request.
|
|
|
|
::
|
|
|
|
[
|
|
{"op": "add", "path": "/login-user", "value": "kvothe"}
|
|
]
|
|
|
|
Similarly, to remove a property such as "login-user" from an image, use
|
|
the following example request.
|
|
|
|
::
|
|
|
|
[
|
|
{"op": "remove", "path": "/login-user"}
|
|
]
|
|
|
|
See Appendix B for more details about the
|
|
'application/openstack-images-v2.1-json-patch' media type.
|
|
|
|
**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 may not be updated or deleted by non-admin users.
|
|
|
|
Add an image tag
|
|
----------------
|
|
|
|
**PUT /v2/images/{image\_id}/tags/{tag}**
|
|
|
|
The tag you want to add should be encoded into the request URI. For
|
|
example, to tag image e7db3b45-8db7-47ad-8109-3fb55c2c24fd with
|
|
'miracle', you would **PUT
|
|
/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/tags/miracle**. The
|
|
request body is ignored.
|
|
|
|
An image tag can be up to 255 characters in length. See the 'image'
|
|
json-schema to determine which characters are allowed.
|
|
|
|
An image can only be tagged once with a specific string. Multiple
|
|
attempts to tag an image with the same string will result in a single
|
|
instance of that string being added to the image's tags list.
|
|
|
|
An HTTP status of 204 is returned.
|
|
|
|
Delete an image tag
|
|
-------------------
|
|
|
|
**DELETE /v2/images/{image\_id}/tags/{tag}**
|
|
|
|
The tag you want to delete should be encoded into the request URI. For
|
|
example, to remove the tag 'miracle' from image
|
|
e7db3b45-8db7-47ad-8109-3fb55c2c24fd, you would **DELETE
|
|
/v2/images/e7db3b45-8db7-47ad-8109-3fb55c2c24fd/tags/miracle**. The
|
|
request body is ignored.
|
|
|
|
An HTTP status of 204 is returned. Subsequent attempts to delete the tag
|
|
will result in a 404.
|
|
|
|
List images
|
|
-----------
|
|
|
|
**GET /v2/images**
|
|
|
|
Request body ignored.
|
|
|
|
Response body will be a list of images available to the client. For
|
|
example:
|
|
|
|
::
|
|
|
|
{
|
|
"images": [
|
|
{
|
|
"id": "da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
|
|
"name": "cirros-0.3.0-x86_64-uec-ramdisk",
|
|
"status": "active",
|
|
"visibility": "public",
|
|
"size": 2254249,
|
|
"checksum": "2cec138d7dae2aa59038ef8c9aec2390",
|
|
"tags": ["ping", "pong"],
|
|
"created_at": "2012-08-10T19:23:50Z",
|
|
"updated_at": "2012-08-10T19:23:50Z",
|
|
"self": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
|
|
"file": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea/file",
|
|
"schema": "/v2/schemas/image"
|
|
},
|
|
{
|
|
"id": "0d5bcbc7-b066-4217-83f4-7111a60a399a",
|
|
"name": "cirros-0.3.0-x86_64-uec",
|
|
"status": "active",
|
|
"visibility": "public",
|
|
"size": 25165824,
|
|
"checksum": "2f81976cae15c16ef0010c51e3a6c163",
|
|
"tags": [],
|
|
"created_at": "2012-08-10T19:23:50Z",
|
|
"updated_at": "2012-08-10T19:23:50Z",
|
|
"self": "/v2/images/0d5bcbc7-b066-4217-83f4-7111a60a399a",
|
|
"file": "/v2/images/0d5bcbc7-b066-4217-83f4-7111a60a399a/file",
|
|
"schema": "/v2/schemas/image"
|
|
},
|
|
{
|
|
"id": "e6421c88-b1ed-4407-8824-b57298249091",
|
|
"name": "cirros-0.3.0-x86_64-uec-kernel",
|
|
"status": "active",
|
|
"visibility": "public",
|
|
"size": 4731440,
|
|
"checksum": "cfb203e7267a28e435dbcb05af5910a9",
|
|
"tags": [],
|
|
"created_at": "2012-08-10T19:23:49Z",
|
|
"updated_at": "2012-08-10T19:23:49Z",
|
|
"self": "/v2/images/e6421c88-b1ed-4407-8824-b57298249091",
|
|
"file": "/v2/images/e6421c88-b1ed-4407-8824-b57298249091/file",
|
|
"schema": "/v2/schemas/image"
|
|
}
|
|
],
|
|
"first": "/v2/images?limit=3",
|
|
"next": "/v2/images?limit=3&marker=e6421c88-b1ed-4407-8824-b57298249091",
|
|
"schema": "/v2/schemas/images"
|
|
}
|
|
|
|
Get images schema
|
|
-----------------
|
|
|
|
**GET /v2/schemas/images**
|
|
|
|
Request body ignored.
|
|
|
|
The response body contains a json-schema document that shows an
|
|
``images`` entity (a container of ``image`` entities). For example:
|
|
|
|
::
|
|
|
|
{
|
|
"name": "images",
|
|
"properties": {
|
|
"images": {
|
|
"items": {
|
|
"type": "array",
|
|
"name": "image",
|
|
"properties": {
|
|
"id": {"type": "string"},
|
|
"name": {"type": "string"},
|
|
"visibility": {"enum": ["public", "private"]},
|
|
"status": {"type": "string"},
|
|
"protected": {"type": "boolean"},
|
|
"tags": {
|
|
"type": "array",
|
|
"items": {"type": "string"}
|
|
},
|
|
"checksum": {"type": "string"},
|
|
"size": {"type": "integer"},
|
|
"created_at": {"type": "string"},
|
|
"updated_at": {"type": "string"},
|
|
"file": {"type": "string"},
|
|
"self": {"type": "string"},
|
|
"schema": {"type": "string"}
|
|
},
|
|
"additionalProperties": {"type": "string"},
|
|
"links": [
|
|
{"href": "{self}", "rel": "self"},
|
|
{"href": "{file}", "rel": "enclosure"},
|
|
{"href": "{schema}", "rel": "describedby"}
|
|
]
|
|
}
|
|
},
|
|
"schema": {"type": "string"},
|
|
"next": {"type": "string"},
|
|
"first": {"type": "string"}
|
|
},
|
|
"links": [
|
|
{"href": "{first}", "rel": "first"},
|
|
{"href": "{next}", "rel": "next"},
|
|
{"href": "{schema}", "rel": "describedby"}
|
|
]
|
|
}
|
|
|
|
Get image schema
|
|
----------------
|
|
|
|
**GET /v2/schemas/image**
|
|
|
|
Request body ignored.
|
|
|
|
The response body contains a json-schema document that shows an
|
|
``image``. For example:
|
|
|
|
::
|
|
|
|
{
|
|
"name": "image",
|
|
"properties": {
|
|
"id": {"type": "string"},
|
|
"name": {"type": "string"},
|
|
"visibility": {"enum": ["public", "private"]},
|
|
"status": {"type": "string"},
|
|
"protected": {"type": "boolean"},
|
|
"tags": {
|
|
"type": "array",
|
|
"items": {"type": "string"}
|
|
},
|
|
"checksum": {"type": "string"},
|
|
"size": {"type": "integer"},
|
|
"created_at": {"type": "string"},
|
|
"updated_at": {"type": "string"},
|
|
"file": {"type": "string"},
|
|
"self": {"type": "string"},
|
|
"schema": {"type": "string"}
|
|
},
|
|
"additionalProperties": {"type": "string"},
|
|
"links": [
|
|
{"href": "{self}", "rel": "self"},
|
|
{"href": "{file}", "rel": "enclosure"},
|
|
{"href": "{schema}", "rel": "describedby"}
|
|
]
|
|
}
|
|
|