Revision as of 19:54, 23 April 2012

This operation will create a new server. The 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. The 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

No parameters

JSON

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

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

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}",
      "name":"{display_server_name}",
      "created":"",
      "tenantId":null,
      "accessIPv4":"{ip_address}",
      "accessIPv6":null,
      "progress":0,
      "metadata":{
      }
   }
}

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

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.

metadata - object

Unused always an empty object.

tenantId

Unused always always null.

accessIPv6

Unused always null.

updated

Unused always null.

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" 
       }
 }
 

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", 
          "name": "test_server_create", 
          "created": "", 
          "tenantId": null, 
          "accessIPv4": "{ip_address}", 
          "accessIPv6": null,
          "progress": 0, 
          "metadata": {}
       }
 }

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

Failure create a server with 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}"
       }
 }

Response Code:

HTTP/1.1 400 Bad Request

Response Body:

{
   "computeFault": 
      {
         "message": "Bad imageRef", 
         "code": 400, 
         "details": ""
      }
}