List servers

Overview

Lists IDs, names, and links for all servers.

Classification

  • List

API Operation Object

  • servers

Synchronous / Asynchronous

  • synchronous

Request

HTTP Request Method

  • GET

HTTP Request Path

{api_endpoint}/v2/{project_id}/servers

HTTP Request Header

Format

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

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
project_id URL UUID(3) Project id required - Terminate 400, 404
token_id Header authentication token string keystone authentication token required - Terminate 401
changes-since Query time/date A time/date stamp for when the server last changed status optional - Terminate 400
status Query String(nolimit) Value of the status of the server so that you can filter on 'ACTIVE' for example optional - - -
marker Query UUID UUID of the server at which you want to set a marker. optional - Terminate 400
name Query String(nolimit) Name of the server as a string. optional - - -
limit Query int Integer value for the limit of values to return. optional - Terminate 400
flavor Query String(nolimit) Name of the flavor in URL format. optional - - -
image Query UUID String Name of the image in UUID format. optional - - -
page_size Query int page size for result 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 specified non date format for "changes-since" query
- invalid tenant id
- specified invalid instance id for marker query
- specified non integer for limit query
401 unauthorized
403 query "status = deleted" by non-admin
404 not found a specified project

HTTP Response Body

Format

{
    "servers": [
        {
            "id": "<instance_id>",
            "links": [
                {
                    "href": "<instance_url>",
                    "rel": "self"
                },
                {
                    "href": "<bookmark_url>",
                    "rel": "bookmark"
                }
            ],
            "name": "<name>"
        },
       <<repeat>>
    ]
}

Response Parameter

Response Parameters
item format description
instance_id UUID String instance id
name String(1-255 characters) name of the server as a string
instance_url instance URL string URL for managing instance
bookmark_url instance URL string URL for instance bookmark

Sample API Request and Response

Sample API Request

Request URI

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

Request Header

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

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

{
    "servers": [
        {
            "id": "<instance_id>",
            "links": [
                {
                    "href": "<instance_url>",
                    "rel": "self"
                },
                {
                    "href": "<bookmark_url>",
                    "rel": "bookmark"
                }
            ],
            "name": "<name>"
        },
       <<repeat>>
    ]
}

Execution Example

HTTP Request

GET /v2/b322a85578de48beba0f92acce57869b/servers 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: 62d528dc0cca4827b0ed465efe1c2588

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 364
X-Compute-Request-Id: req-564222f3-6cf0-4a8e-bd39-30718217a3d7
Date: Thu, 17 Jul 2014 04:21:06 GMT

{"servers": [{"id": "523a0a98-01b8-4c18-acfe-3c4ceb85c0ea", "links": [{"href": "http://192.168.150.51:8774/v2/b322a85578de48beba0f92acce57869b/servers/523a0a98-01b8-4c18-acfe-3c4ceb85c0ea", "rel": "self"}, {"href": "http://192.168.150.51:8774/b322a85578de48beba0f92acce57869b/servers/523a0a98-01b8-4c18-acfe-3c4ceb85c0ea", "rel": "bookmark"}], "name": "Testvm1"}]}

Error Execution Example

HTTP Request

GET /v2/b322a85578de48beba0f92acce57869b/servers HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:8774
X-Auth-Token: 5565d8f69d9a43b698aa30f30ebc681b
Content-type: application/json
Accept: application/json

HTTP Response

HTTP/1.1 400 Bad Request
Content-Length: 188
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-149d17ec-c033-4527-b392-05293820818f
Date: Tue, 06 Oct 2015 07:07:02 GMT

{"badRequest": {"message": "Malformed request URL: URL's project_id 'b322a85578de48beba0f92acce57869b' doesn't match Context's project_id 'b17a6492bfa54441910e15f07c983384'", "code": 400}}
Compute(Nova)
Create server