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>>
]

<< To add locations >>

[

    {
        "path": "/locations/<position>",
        "value": {
            "metadata" : <metadata>,
            "url": "<location_url>"
        },
        "op": "<operation>"
    },
    <<repeat>>
]

<< To remove locations >>

[

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

<< To replace locations >>

[

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

<<To add properties >>

[

    {
        "path": "/locations",
        "value": [
            {
                "metadata" : <metadata>,
                "url": "<location_url>"
            },
            <<repeat>>
        ],
        "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 / location in the specified image
remove … removes the specified image’s property / location
replace … replaces the value of a specified image’s property / location
required - Terminate 500
position Body String (positive number or ‘-‘ to specify last index) The position to add / remove a location to / from the image’s locations list required - Terminate 400
location_url Body URL String URL to access the image file kept in external store required - Terminate 400
metadata Body
json array (2^16 - 1 bytes)
<<format is shown below>>
{
“key”: “value”,
<<repeat>>
}
The location metadata required - Terminate 400, 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 <position> of images’s location when <operation> is add / remove
- specify a existing <location> when add locations (If metadata is not same, the location is accepted as different)
- specify a invalid <value> for a property or location when <operation> is add / replace
- try to replace image’s non-empty locations to non-empty locations
- try to add / replace <location> when disk_format and container_format are not set in the specified image
401 unauthorized
403
specify read_only properties in <path>
read_only properties : checksum, created_at, direct_url, 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
- The number of locations 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>>
            ],
            "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>"

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

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>>
]

<< To add locations >>

[

    {
        "path": "/locations/<position>",
        "value": {
            "metadata" : <metadata>,
            "url": "<location_url>"
        },
        "op": "<operation>"
    },
    <<repeat>>
]

<< To remove locations >>

[

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

<< To replace locations >>

[

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

<<To add properties >>

[

    {
        "path": "/locations",
        "value": [
            {
                "metadata" : <metadata>,
                "url": "<location_url>"
            },
            <<repeat>>
        ],
        "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>>
            ],
            "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>"

}
  • * 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", "direct_url": "file:///home/stack/test", "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.