Update image

Overview

Updates a specified image.

Classification

  • Update

API Operation Object

  • images

Synchronous / Asynchronous

  • synchronous

Request

HTTP Request Method

  • PATCH

HTTP Request Path

{api_endpoint}/v2/images/{image_id}

HTTP Request Header

Format

X-Auth-Token: <token_id>
Content-Type: application/openstack-images-v2.1-json-patch
(Content-Type: application/openstack-images-v2.0-json-patch is deprecated)

  • User-Agent, Host, Accept, Content-Length fields are automatically added

HTTP Request Body

Format

* The request body can be specified in six patterns.

<<To add properties >>

[

    {
        "path": "/<path>",
        "value": <value>,
        "op": "<operation>"
    },
    <<repeat>>
]

<<To remove properties >>

[

    {
        "path": "/<path>",
        "op": "<operation>"
    },
    <<repeat>>
]

<<To replace properties >>

[

    {
        "path": "/<path>",
        "value": <value>,
        "op": "<operation>"
    },
    <<repeat>>
]

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

path

Body

String

Image's property

required

-

Terminate

400, 500

value

Body

String (json format)

Value of image property used in add / replace operation expressed in JSON notation (For example, strings must be quoted, numeric values are unquoted)

required (when operation is add or replace)

-

Terminate

400

operation

Body

String ("add", "remove", "replace")
add … adds a new property in the specified image
remove … removes the specified image's property

replace … replaces the value of a specified image's property

required

-

Terminate

500

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

400

empty body

-

call with malformed JSON

-

key 'op' is not specified

-

key 'path' is not specified

-

<path> does not start with "/"

-

<path> contains adjacent "/"

-

<path> end with "/"

-

<path> does not contains valid token

-

<path> contains not part of a recognized escape sequence

-

<path> depth does not match specified <operation> path depth (add's and remove's path depth is 2, replace's path depth is 1)

-

<value> is not specified when <operation> is add / remove

-

specify a invalid <value> for a property or location when <operation> is add / replace

401

unauthorized

403
specify read_only properties in <path>

read_only properties : checksum, created_at, file, schema, self, size, status, updated_at, virtual_size

-
specify reserved properties in <path>

reserved properties : deleted, deleted_at, is_public, locations, owner

-

specify a properties in <path> which is not allowed to remove

-

requested for replacing container_format of not 'queued' status image

-

requested for replacing disk_format of not 'queued' status image

-

if authority of non admin, image has no owner

-

if authority of non admin, requested by user whose project is not the owner of specified private image

-

if authority of non admin, requested for replacing visibility to public

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)

409

Specify a exsiting property of the specified image when <operation> is add

-

Specify a non-existent property of the specified image when <operation> is replace / remove

413

The number of image properties exceeds the limit

-

The number of image tags exceeds the limit

-

Specified image's file (location) size exceeds the total capacity which user can use across all storage systems

415

Content-Type does not specify 'application/openstack-images-v2.1-json-patch'

500

specify a invalid <operation>

-

specify 'None' in <path>

-

specify int in the value of <metadata>

-

specify '2^16 - 1' or more value in the value of <metadata>

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>>
            ],
            *"<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>"

}

  • * 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

metadata
json array (2^16 - 1 bytes)
<<format is shown below>>
{
"key": "value",
<<repeat>>

}

The location metadata

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

Sample API Request and Response

Sample API Request

Request URI

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

Request Header

X-Auth-Token: <token_id>
Content-Type: application/openstack-images-v2.1-json-patch
(Content-Type: application/openstack-images-v2.0-json-patch is deprecated)

  • User-Agent, Host, Accept, Content-Length fields are automatically added

Request Body

* The request body can be specified in six patterns.

<<To add properties >>

[

    {
        "path": "/<path>",
        "value": <value>,
        "op": "<operation>"
    },
    <<repeat>>
]

<<To remove properties >>

[

    {
        "path": "/<path>",
        "op": "<operation>"
    },
    <<repeat>>
]

<<To replace properties >>

[

    {
        "path": "/<path>",
        "value": <value>,
        "op": "<operation>"
    },
    <<repeat>>
]

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>>
            ],
            *"<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>"

}

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

Execution Example

HTTP Request

PATCH /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: 896d37fcb1f34f1392537b0ffbc60064
Content-Type: application/openstack-images-v2.1-json-patch
Content-Length: 85

[{"path":"/extra3", "value":"extra3", "op":"add"}, {"path":"/extra2", "op":"remove"}]

HTTP Response

HTTP/1.1 200 OK
Content-Length: 713
Content-Type: application/json; charset=UTF-8
X-Openstack-Request-Id: req-133e4f2f-118a-4db9-8287-38ae2a9eeabc
Date: Wed, 24 Sep 2014 11:06:54 GMT

{"status": "active", "schema": "/v2/schemas/image", "name": "private_admin_admin", "tags": ["tag1", "tag2", "tag3"], "updated_at": "2014-09-24T11:06:54Z", "container_format": "bare", "min_ram": 0, "disk_format": "qcow2", "locations": [{"url": "file:///home/stack/test", "metadata": {"meta_key": "meta"}}], "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",  "id": "5521fbf2-0b89-4b7c-91b5-e3afbecd4a35", "size": 25165824}

Error Execution Example

HTTP Request

PATCH /v2/images/455af5de-e503-46de-9884-f0334f5b17e0 HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:9292
Accept: */*
X-Auth-Token: fa72b568b7874a35a835b2639f51fbbc
Content-type: application/openstack-images-v2.1-json-patch
Content-Length: 83

HTTP Response

HTTP/1.1 400 Bad Request
Content-Length: 157
Content-Type: text/html; charset=UTF-8
X-Openstack-Request-Id: req-2597d5da-b568-471d-84f8-711c0de0dd2e
Date: Thu, 15 Oct 2015 12:17:16 GMT

400 Bad Request

Malformed JSON in request body.
Get image details
Delete image