Revision as of 07:10, 20 May 2013

This operation will create a new server. Server creation is asynchronous, the progress can be checked with the URL in the response Location header or the self link in the body.

POST /servers

This operation will create a new server. Server creation is asynchronous, the progress can be checked with the URL in the response Location header or the self link in the body.

Parameters

JSON

{
   "server":{
      "name":"{display_server_name}",
      "imageRef":"http://{server_name}/images/{image_id}/",
      "flavorRef":"http://{server_name}/flavors/{flavor_id}/",
      "adminPass":"{initial_password}",
      "zone": "{zone_textkey}"
   }
}

name - string

Display name for this server

imageRef - string

Absolute URL of the Image to use

flavorRef - string

Absolute URL of the Flavor to use

adminPass - string

Initial admin password. If not specified, the automatically generated password would be returned.

zone

Zone textkey

Result

JSON

{
   "server":{
      "status":"{state_status}",
      "updated":null,
      "hostId":"",
      "addresses":{
         "public":[
            {
               "version":4,
               "addr":"{ip_address}"
            }
         ],
         "private":[
            {
               "version":4,
               "addr":"{ip_address}"
            }
         ]
      },
      "links":[
         {
            "href":"http://{server_name}/servers/{server_id}/",
            "rel":"self"
         }
      ],
      "image":{
         "name":"{display_image_name}",
         "links":[
            {
               "href":"http://{server_name}/images/{image_id}/",
               "rel":"self"
            }
         ],
         "id":"{image_id}"
      },
      "userId":"{user_account_id}",
      "flavor":{
         "name":"{display_flavor_name}",
         "links":[
            {
               "href":"{server_name}/flavors/{flavor_id}/",
               "rel":"self"
            }
         ],
         "id":{flavor_id}
      },
      "id":"{server_id}",
      "zone": "{zone_textkey}",
      "name":"{display_server_name}",
      "adminPass": "{initial_password}"
      "created":"",
      "tenantId":null,
      "accessIPv4":"{ip_address}",
      "accessIPv6":null,
      "progress":0,
      "metadata":{
      }
   }
}

• When a server is in pending status (has not completed the provisioning process), the creation timestamp and hostId that are returned will be empty strings.

server

id - string

Unique identifier for this server.

links - list

Hypermedia for this resource.

status - string

Current state of the server. Values: BUILD, ACTIVE, SUSPENDED, DELETED, UNKNOWN

hostId - string

Id of the physical host this virtual machine is running on.

userId - string

Unique identifier for the owner of this server.

name - string

Display name for this server.

created - string

The date and time this server was created. ISO 8601 format, YYYY-MM-DDTHH:MM:SS.

accessIPv4 - string

The default included public IPv4 address.

progress - number

The progress of the current this server while in the BUILD status. The value is in the range of 0 - 100, but currently will only even be 0, 50, 100.

adminPass - string

The admin password. Not null only in the creating server response.

metadata - object

Unused always an empty object.

tenantId

Unused always always null.

accessIPv6

Unused always null.

updated

Unused always null.

zone

Zone text key

addresses

addresses.public.version - number

IP version of this address. Values: 4

addresses.public.addr = string

Public IP address of this server

addresses.private.version - number

IP version of this address. Values: 4

addresses.private.addr - string

Private IP address of this server

image

image.name - string

The display name of the image this server is based on.

image.links - list

Hypermedia for the image.

image.id - string

Unique identifier for image this server is based on.

flavor

flavor.name - string

The display name of the flavor this server is based on.

flavor.links - list

Hypermedia for the flavor.

flavor.id - string

Unique identifier for flavor this server is based on.

Response Codes

Success

HTTP/1.1 202 Accepted

Request is accepted.

Failure

HTTP/1.1 400 Bad Request

The resource used for creating server is not found.

Examples

Successfully create a new server

POST http://{api_server}/servers

Request Headers:

   Content-Type:application/json
   Charset=UTF-8
   Authorization:Base64-encoded username & password string

Request Body:

 {
    "server" : 
       {
          "flavorRef" : "http://{api_server}//flavors/1",
          "name" : "test_server_create", 
          "imageRef" : "http://{api_server}//images/test_public_image",
          "zone": "AUS001"
       }
 }
 

Response Code:

HTTP/1.1 202 Accepted

Response Body:

 {
    "server": 
       {
          "status": "BUILD", 
          "updated": null, 
          "hostId": "", 
          "addresses": 
             {
                "public": [
                   {
                      "version": 4, 
                      "addr": "{ip_address}"
                   }
                ],
                "private": [
                   {
                      "version": 4, 
                      "addr":  "{ip_address}"
                   }
                ]
             }, 
          "links": [
             {
                "href": "http://{api_server}/servers/167/", 
                "rel": "self"
             }
          ], 
          "imageRef": 
             {
                "name": "CentOS 5 Plesk", 
                "links": [
                   {
                      "href": "http://{api_server}/images/test_public_image/", 
                      "rel": "self"
                   }
                ],
                "id": "test_public_image"
          }, 
          "userId": "{user_account_id}", 
          "flavorRef":  
             {
                "name": "", 
                "links": [
                   {
                      "href": "http://{api_server}/flavors/1/", 
                      "rel": "self"
                   } 
                ], 
                "id": "1"
             }, 
          "id": "167",
          "zone": "AUS001",
          "name": "test_server_create", 
          "adminPass": "{auto_generated_password}"
          "created": "", 
          "tenantId": null, 
          "accessIPv4": "{ip_address}", 
          "accessIPv6": null,
          "progress": 0, 
          "metadata": {}
       }
 }

• When a server is in pending status (has not completed the provisioning process), the creation timestamp and hostId that are returned will be empty strings.

Failure while trying to create a server with a bad request body

POST http://{api_server}/servers

Request Headers:

   Content-Type:application/json
   Charset=UTF-8
   Authorization:Base64-encoded username & password string

Request Body:

 {
    "server" : 
       { 
          "flavorRef" : "http://{api_server}//flavors/{flavor_id}",
          "name" : "{display_server_name}",
          "imageRef" : "http://{api_server}//images/{fake_image_id}",
          "zone": "AUS001"
       }
 }

Response Code:

HTTP/1.1 400 Bad Request

Response Body:

{
   "computeFault": 
      {
         "message": "Bad imageRef", 
         "code": 400, 
         "details": "",
         "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
      }
}