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