Get image details

Overview

Gets details for a specified image.

Classification

  • Show

API Operation Object

  • images

Synchronous / Asynchronous

  • synchronous

Request

HTTP Request Method

  • GET

HTTP Request Path

{api_endpoint}/v2/images/{image_id}

HTTP Request Header

Format

X-Auth-Token: <token_id>
  • User-Agent, Host, Accept fields are automatically added

HTTP Request Body

Format

  • none

Request Parameter

Request Parameters
name style format description required/optional default value action for invalid parameter response code for invalid parameter
image_id URL UUID An identifier for the image required - Terminate 404
token_id Header authentication token string keystone authentication token required - Terminate 401

Response

HTTP Response Header

Format

HTTP/1.1 <response_code> <message>       (ex. 200 OK)

  • <response_code>: see "HTTP Responses" section

  • <message>: message based on the response code

    • skip auto insert field such as "X-Compute-Request-Id" and "Content-Length", "Date"

Response Code

Response Codes
response code condition
200 normal end
401 unauthorized
403 Not authorized to perform the requested action
404 specify non-existent image_id
- specify the image_id of deleted image
- if authority of non admin, requested by user whose project is not the member and not the owner of specified private image (assuming that the image has owner)
500 Internal Error

HTTP Response Body

Format

{

            "status": "<image_status>",
            "name": "<image_name>",
            "tags": ["<tag>", <<repeat>> ],
            "container_format": "<container_format>",
            "created_at": "<created_time>",
            "disk_format": "<disk_format>",
            "locations": [
                {
                    "url": "<location_url>",
                    "metadata": <metadata>
                },
                <<repeat>>
            ],
            "direct_url": "<direct_url>",
            *"<extra_key>": "<extra_value>",
            "updated_at": "<updated_time>",
            "visibility": "<visibility>",
            "self": "<self>",
            "min_disk": <minimum_disk_size>,
            "protected": <protected_flag>,
            "id": "<image_id>",
            "file": "<file>",
            "checksum": "<checksum>",
            "owner": "<owner>",
            "size": <size>,
            "min_ram": <minimum_ram_size>,
            "schema": "<image_schema>",
            "virtual_size": "<virtual_size>",
            "hw_firmware_type": "<hw_firmware_type>"

}
  • * There are multiple set of <extra_key> and <extra_value> which user added

Response Parameter

Response Parameters
item format description
image_status String (queued, saving, active, killed, deleted, pending_delete) Status of the image
image_name String (1-255 characters) Descriptive name for the image
tag String (1-255 characters) String related to the image
container_format String (bare) Format of the container
created_time time/date Date and time of image registration
disk_format String (raw, qcow2, iso) Format of the disk
location_url URL String URL to access the image file kept in external store (it is shown when 'show_multiple_locations' option is enabled)
metadata
json array (2^16 - 1 bytes)
<<format is shown below>>
{
"key": "value",
<<repeat>>
}
 The location metadata
direct_url URL String URL to access the image file kept in external store (it is shown when 'show_image_direct_url' option is enabled)
extra_key String (1-255 characters) The key of the extra properties
extra_value text (2^16 - 1 bytes) The value of the extra properties
updated_time time/date Date and time of the last image modification
visibility String (public, private) Scope of image accessibility
self URL String URL for the virtual machine image
minimum_disk_size integer Amount of disk space (in GB) required to boot image
protected_flag boolean If true, image will not be deletable
image_id UUID An identifier for the image
file URL String URL for the virtual machine image file
checksum MD5 md5 hash of image contents
owner UUID(3) Owner of the image
size integer Size of image file in bytes
minimum_ram_size integer Amount of ram (in MB) required to boot image
image_schema URL String URL for schema of the virtual machine image
virtual_size integer The virtual size of the image. The value might be null (JSON null data type)
hw_firmware_type(optional) String If uefi, image enable UEFI BOOT

Sample API Request and Response

Sample API Request

Request URI

https://example.com/v2/images/{image_id}

Request Header

X-Auth-Token: ajk3adjiown02
  • User-Agent, Host, Accept fields are automatically added

Request Body

  • none

Sample API Response

Response Header

HTTP/1.1 200 OK

  • <response_code>: see "HTTP Responses" section

  • <message>: message based on the response code

    • skip auto insert field such as "X-Compute-Request-Id" and "Content-Length", "Date"

Response Body

{

            "status": "<image_status>",
            "name": "<image_name>",
            "tags": ["<tag>", <<repeat>> ],
            "container_format": "<container_format>",
            "created_at": "<created_time>",
            "disk_format": "<disk_format>",
            "locations": [
                {
                    "url": "<location_url>",
                    "metadata": <metadata>
                },
                <<repeat>>
            ],
            "direct_url": "<direct_url>",
            *"<extra_key>": "<extra_value>",
            "updated_at": "<updated_time>",
            "visibility": "<visibility>",
            "self": "<self>",
            "min_disk": <minimum_disk_size>,
            "protected": <protected_flag>,
            "id": "<image_id>",
            "file": "<file>",
            "checksum": "<checksum>",
            "owner": "<owner>",
            "size": <size>,
            "min_ram": <minimum_ram_size>,
            "schema": "<image_schema>",
            "virtual_size": "<virtual_size>"

}
  • * There are multiple set of <extra_key> and <extra_value> which user added

Execution Example

HTTP Request

GET /v2/images/5521fbf2-0b89-4b7c-91b5-e3afbecd4a35 HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.11.141:9292
Accept: */*
X-Auth-Token: 4086d667aa3648fd96a7886cbb6354c1

HTTP Response

HTTP/1.1 200 OK
Content-Length: 811
Content-Type: application/json; charset=UTF-8
X-Openstack-Request-Id: req-b7bc75bc-5991-498a-a004-6fc89a4b8189
Date: Wed, 24 Sep 2014 11:39:38 GMT

{"status": "active", "schema": "/v2/schemas/image", "name": "private_admin_admin", "tags": ["tag1", "tag2", "tag3"], "updated_at": "2014-09-24T11:13:10Z", "container_format": "bare", "min_ram": 0, "disk_format": "qcow2", "locations": [{"url": "file:///home/stack/test", "metadata": {"replace_01": "replace_01_value"}}, {"url": "file:///home/stack/test", "metadata": {"replace_02": "replace_02_value"}}], "visibility": "private", "self": "/v2/images/5521fbf2-0b89-4b7c-91b5-e3afbecd4a35", "extra1": "extra1", "protected": false, "extra3": "extra3", "file": "/v2/images/5521fbf2-0b89-4b7c-91b5-e3afbecd4a35/file", "owner": "014908bf180c4004a6c289d2d95b2285", "min_disk": 0, "created_at": "2014-09-24T11:05:39Z", "direct_url": "file:///home/stack/test", "id": "5521fbf2-0b89-4b7c-91b5-e3afbecd4a35", "size": 25165824, "virtual_size": null}

Error Execution Example

HTTP Request

GET /v2/images/455af5de-e503-46de-9884-f0334f5b17eo HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:9292
Accept: */*
X-Auth-Token: 9e55330892434fc78e86ee09e50a95ee

HTTP Response

HTTP/1.1 404 Not Found
Content-Length: 181
Content-Type: text/html; charset=UTF-8
X-Openstack-Request-Id: req-d817dd90-7b6b-4d6a-8901-4c1ed17a8087
Date: Thu, 15 Oct 2015 12:00:51 GMT

404 Not Found

No image found with ID 455af5de-e503-46de-9884-f0334f5b17eo
Create image
Update image