Update server

Overview

Updates the editable attributes of the specified server.

Classification

  • Update

API Operation Object

  • servers

Synchronous / Asynchronous

  • synchronous

Request

HTTP Request Method

  • PUT

HTTP Request Path

{api_endpoint}/v2/{project_id}/servers/{server_id}

HTTP Request Header

Format

Accept-Encoding: gzip, deflate, compress (optional)
Accept: application/json
X-Auth-Token: <token_id>
Content-Type: application/json

HTTP Request Body

Format

{
    "server": {
        "accessIPv4": "<access_ipv4>",
        "accessIPv6": "<access_ipv6>",
        "name": "<name>"
    }
}

Request Parameter

Request Parameters
name style format description required/optional default value action for invalid parameter response code for invalid parameter
project_id URL UUID(3) Project id required - Terminate 400, 404
server_id URL UUID String instance id required - Terminate 404
token_id Header authentication token string keystone authentication token required - Terminate 401
access_ipv4 Body ipv4 format IPv4 address optional - Terminate 400
access_ipv6 Body ipv6 format IPv6 address optional - Terminate 400
name Body String(1-255 characters) Name of the server as a string optional - Terminate 400

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 instance name is empty or more than 255 characters
- ipv4 address is not proper IPv4 format
- ipv6 is not proper IPv6 format
401 unauthorized
404 not found a specified instance
- not found a specified project
- not authorized to perform the requested action
422 not found "server" entity in body

HTTP Response Body

Format

{
    "servers": {
            "OS-DCF:diskConfig": "<diskconfig>",
            "accessIPv4": "<access_ipv4>",
            "accessIPv6": "<access_ipv6>",
            "addresses": {
                "<network_name>": [
                    {
                        "OS-EXT-IPS-MAC:mac_addr": "<MAC_address>",
                        "OS-EXT-IPS:type": "<address_type>",
                        "addr": "<ip_address>",
                        "version": <ip_address_version>
                    },
                    <<repeat>>
                ]
            },
            "created": "<created_time>",
            "flavor": {
                "id": "<flavor_id>",
                "links": [
                    {
                        "href": "<flavor_bookmark>",
                        "rel": "bookmark"
                    }
                ]
            },
            "hostId": "<host_id>",
            "id": "<instance_id>",
            "image": {
                "id": "<image_id>",
                "links": [
                    {
                        "href": "<image_bookmark>",
                        "rel": "bookmark"
                    }
                ]
            },
            "links": [
                {
                    "href": "<self_management_url>",
                    "rel": "self"
                },
                {
                    "href": "<self_bookmark_url>",
                    "rel": "bookmark"
                }
            ],
            "metadata": {
                "<metadata_key>":"<metadata_value>"
             },
            "name": "<name>",
            "progress": <progress>,
            "status": "<status>",
            "tenant_id": "<tenant_id>",
            "updated": "<updated_time>",
            "user_id": "<user_id>"
        }
}

Response Parameter

Response Parameters
item format description
diskconfig MANUAL or AUTO disk config
access_ipv4 IPv4address IPv4 address
access_ipv6 String(1-255 characters) IPv6 address
network_name String(1-255 characters) network name
MAC_address MAC Address MAC address for instance
address_type fixed or floating types of IP addresses.
ip_address IPv4 address or IPv6 address ip address for instance
ip_address_version int(4 or 6) ip protocol version
created_time time/date created time of instance
flavor_id String(1-255 characters) flavor id
flavor_bookmark URL String Bookmark URL for flavor
host_id String(1-255 characters) host id
instance_id UUID instance id
image_id UUID image ID
image_bookmark URL String bookmark URL for image
self_management_url URL String management URL for instance
self_bookmark_url URL String bookmark URL for instance
metadata_key String(1-255 characters) metadata key
metadata_value String(1-255 characters) metadata value
name String(1-255 characters) instance name
progress int boot progress for instance
status String(1-255 characters) state of instance
tenant_id tenant id(2) tenant id
updated_time time/date update time
user_id String(1-255 characters) owner of instance

Sample API Request and Response

Sample API Request

Request URI

https://example.com/v2/{project_id}/servers/{server_id}

Request Header

Accept-Encoding: gzip, deflate, compress (optional)
Accept: application/json
X-Auth-Token: ajk3adjiown02
Content-Type: application/json

Request Body

{
    "server": {
        "accessIPv4": "<access_ipv4>",
        "accessIPv6": "<access_ipv6>",
        "name": "<name>"
    }
}

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

{
    "servers": {
            "OS-DCF:diskConfig": "<diskconfig>",
            "accessIPv4": "<access_ipv4>",
            "accessIPv6": "<access_ipv6>",
            "addresses": {
                "<network_name>": [
                    {
                        "OS-EXT-IPS-MAC:mac_addr": "<MAC_address>",
                        "OS-EXT-IPS:type": "<address_type>",
                        "addr": "<ip_address>",
                        "version": <ip_address_version>
                    },
                    <<repeat>>
                ]
            },
            "created": "<created_time>",
            "flavor": {
                "id": "<flavor_id>",
                "links": [
                    {
                        "href": "<flavor_bookmark>",
                        "rel": "bookmark"
                    }
                ]
            },
            "hostId": "<host_id>",
            "id": "<instance_id>",
            "image": {
                "id": "<image_id>",
                "links": [
                    {
                        "href": "<image_bookmark>",
                        "rel": "bookmark"
                    }
                ]
            },
            "links": [
                {
                    "href": "<self_management_url>",
                    "rel": "self"
                },
                {
                    "href": "<self_bookmark_url>",
                    "rel": "bookmark"
                }
            ],
            "metadata": {
                "<metadata_key>":"<metadata_value>"
             },
            "name": "<name>",
            "progress": <progress>,
            "status": "<status>",
            "tenant_id": "<tenant_id>",
            "updated": "<updated_time>",
            "user_id": "<user_id>"
        }
}

Execution Example

HTTP Request

PUT /v2/5d8b99310e6c49eaa5413aa659170deb/servers/cbce6087-6156-453c-a512-60bf3d75d69f HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.150.51:8774
Accept-Encoding: gzip, deflate, compress
Accept: application/json
X-Auth-Token: 8f305e33f23745e8ac3abbd894d7c546
Content-Type: application/json
Content-Length: 101

{"server": {"accessIPv4":"192.168.11.5", "accessIPv6": "::babe:67.23.10.132","name": "RenameTestvm"}}

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1151
X-Compute-Request-Id: req-07d8b199-595d-4324-a306-1a758414de82
Date: Thu, 24 Jul 2014 02:40:07 GMT

{"server": {"status": "ACTIVE", "updated": "2014-07-24T02:40:07Z", "hostId": "304b720487da712fbd57d787e93f0a3d52aed8672b19bdf51f36792a", "addresses": {"private": [{"version": 4, "addr": "10.0.0.2"}]}, "links": [{"href": "http://192.168.150.51:8774/v2/5d8b99310e6c49eaa5413aa659170deb/servers/cbce6087-6156-453c-a512-60bf3d75d69f", "rel": "self"}, {"href": "http://192.168.150.51:8774/5d8b99310e6c49eaa5413aa659170deb/servers/cbce6087-6156-453c-a512-60bf3d75d69f", "rel": "bookmark"}], "image": {"id": "1fd5ab9b-1769-4dd5-b0bd-e075614cc866", "links": [{"href": "http://192.168.150.51:8774/5d8b99310e6c49eaa5413aa659170deb/images/1fd5ab9b-1769-4dd5-b0bd-e075614cc866", "rel": "bookmark"}]}, "flavor": {"id": "2", "links": [{"href": "http://192.168.150.51:8774/5d8b99310e6c49eaa5413aa659170deb/flavors/2", "rel": "bookmark"}]}, "id": "cbce6087-6156-453c-a512-60bf3d75d69f", "user_id": "f5a98f28f61e4fd19622f9016c481d48", "name": "RenameTestvm", "created": "2014-07-24T00:26:07Z", "tenant_id": "5d8b99310e6c49eaa5413aa659170deb", "OS-DCF:diskConfig": "MANUAL", "accessIPv4": "192.168.11.5", "accessIPv6": "::babe:4317:a84", "progress": 0, "metadata": {}}}

Error Execution Example

HTTP Request

PUT /v2/5d8b99310e6c49eaa5413aa659170deb/servers/cbce6087-6156-453c-a512-60bf3d75d69f HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:8774
X-Auth-Token: fd3ab9d54e204c88bc66c6918d01ede5
Content-type: application/json
Accept: application/json
Content-Length: 102

{"server": {"accessIPv4":"192.168.11.5", "accessIPv6": "::babe:67.23.10.132","name": "RenameTestvm",}}

HTTP Response

HTTP/1.1 400 Bad Request
Content-Length: 66
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-6cdb46b0-46b0-4202-8b0e-43d60f943e6d
Date: Mon, 28 Sep 2015 10:45:00 GMT

{"badRequest": {"message": "Malformed request body", "code": 400}}
Get server details
Delete server