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"
}
Pagination
This call is designed to return a subset of the larger collection of images while providing a link that can be used to retrieve the next. 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 there a 'next' link is no longer provided. The next link will preserve any query parameters you send in your initial request. The 'first' link can be used to jump back to the first page of the collection.
If you prefer to paginate through images manually, the API provides two query parameters: 'limit' and 'marker'. The limit parameter is used to request a specific page size. Expect a response to a limited request to return between zero and limit items. The marker parameter is used to indicate the id of the last-seen image. The typical pattern of limit and marker is to make an initial limited request then to use the id of the last image from the response as the marker parameter in a subsequent limited request.
Filtering
The list operation accepts several types of query parameters intended to filter the results of the returned collection.
A client can provide direct comparison filters using most image attributes (i.e. name=Ubuntu, visibility=public, etc). A client cannot filter on tags or anything defined as a 'link' in the json-schema (i.e. self, file, schema).
The 'size_min' and 'size_max' query parameters can be used to do greater-than and less-than filtering of images based on their 'size' attribute ('size' is measured in bytes and refers to the size of an image when stored on disk). For example, sending a size_min filter of 1048576 and size_max of 4194304 would filter the container to include only images that are between one and four megabytes in size.
Sorting
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'.
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.
