ServerCreate

From Hostway API Documentation
(Difference between revisions)
Jump to: navigation, search
m (1 revision: Release 98)
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
<pre style="color:red">Needs production update</pre>
+
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.
  
−
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''' /accounts/''{accountId}''/flexcloud/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.
  
−
'''POST''' /servers
+
== Request ==
 +
=== Request Parameters ===
 +
; accountId - ''string''
 +
: The selected account Id.
  
−
== Parameters ==
 
 
=== JSON ===
 
=== JSON ===
−
<big><source lang="javascript">
+
<nowiki>
 
{
 
{
 
   "server":{
 
   "server":{
 
       "name":"{display_server_name}",
 
       "name":"{display_server_name}",
−
       "imageRef":"http://{server_name}/images/{image_id}/",
+
       "imageRef":"http://{server_name}/accounts/{accountId}/flexcloud/images/{image_id}/",
−
       "flavorRef":"http://{server_name}/flavors/{flavor_id}/"
+
       "flavorRef":"http://{server_name}/accounts/{accountId}/flexcloud/flavors/{flavor_id}/",
 +
      "securityGroupRef":"http://{server_name}/accounts/{accountId}/flexcloud/os-security-groups/{security_group_id}/",
 +
      "adminPass":"{initial_password}",
 +
      "zone": "{zone_textkey}"
 
   }
 
   }
−
}
+
}</nowiki>
−
</source></big>
+
  
 
; name - ''string''
 
; name - ''string''
Line 25: Line 30:
 
; flavorRef - ''string''
 
; flavorRef - ''string''
 
: Absolute URL of the [[Flavor]] to use
 
: Absolute URL of the [[Flavor]] to use
 +
 +
; securityGroupRef - ''string''
 +
: Absolute URL of the [[SecurityGroup]] to use
 +
 +
; adminPass - ''string''
 +
: Initial admin password. If not specified, the automatically generated password would be returned.
 +
 +
; zone
 +
: Zone textkey
  
 
== Result ==
 
== Result ==
 
=== JSON ===
 
=== JSON ===
−
<big><source lang="javascript">
+
<nowiki>
 
{
 
{
 
   "server":{
 
   "server":{
−
       "status":"BUILD",
+
       "status":"{state_status}",
 
       "updated":null,
 
       "updated":null,
 
       "hostId":"",
 
       "hostId":"",
Line 50: Line 64:
 
       "links":[
 
       "links":[
 
         {
 
         {
−
             "href":"http://{server_name}/servers/{server_id}/",
+
             "href":"http://{server_name}/accounts/{accountId}/flexcloud/servers/{server_id}/",
 
             "rel":"self"
 
             "rel":"self"
 
         }
 
         }
 
       ],
 
       ],
 
       "image":{
 
       "image":{
−
         "name":"Ubuntu 10.10 x64",
+
         "name":"{display_image_name}",
 
         "links":[
 
         "links":[
 
             {
 
             {
−
               "href":"http://{server_name}/images/20GB_Ubuntu%2010.10%20x64%20R1soft/",
+
               "href":"http://{server_name}/accounts/{accountId}/flexcloud/images/{image_id}/",
 
               "rel":"self"
 
               "rel":"self"
 
             }
 
             }
 
         ],
 
         ],
−
         "id":"20GB_Ubuntu 10.10 x64 R1soft"
+
         "id":"{image_id}"
 +
      },
 +
      "securityGroup": {
 +
        "id":"{security_group_id}",
 +
        "links":[
 +
            {
 +
              "href":"http://{api_server}/accounts/{accountId}/flexcloud/os-security-groups/{security_group_id}/",
 +
              "rel":"self"
 +
            }
 +
        ]
 
       },
 
       },
 
       "userId":"{user_account_id}",
 
       "userId":"{user_account_id}",
 
       "flavor":{
 
       "flavor":{
−
         "name":"1024MB Server3",
+
         "name":"{display_flavor_name}",
 
         "links":[
 
         "links":[
 
             {
 
             {
−
               "href":"{server_name}/flavors/3/",
+
               "href":"{server_name}/accounts/{accountId}/flexcloud/flavors/{flavor_id}/",
 
               "rel":"self"
 
               "rel":"self"
 
             }
 
             }
 
         ],
 
         ],
−
         "id":3
+
         "id":{flavor_id}
 
       },
 
       },
 
       "id":"{server_id}",
 
       "id":"{server_id}",
 +
      "zone": "{zone_textkey}",
 
       "name":"{display_server_name}",
 
       "name":"{display_server_name}",
 +
      "adminPass": "{initial_password}"
 
       "created":"",
 
       "created":"",
 
       "tenantId":null,
 
       "tenantId":null,
Line 83: Line 108:
 
       "progress":0,
 
       "progress":0,
 
       "metadata":{
 
       "metadata":{
−
 
 
       }
 
       }
 
   }
 
   }
−
}
+
}</nowiki>
−
</source></big>
+
−
 
+
  
−
* When a server is still pending (has not completed the provisioning process), the creation timestamp and hostId that are returned will be empty string.
+
* 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 ====
 
==== server ====
 
; id - ''string''
 
; id - ''string''
Line 99: Line 121:
  
 
; status - ''string''
 
; status - ''string''
−
: Current state of the server. Values: '''BUILD''', '''ACTIVE''', '''SUSPENDED''', '''DELETED''', '''UNKNOWN'''
+
: Current state of the server. Values: '''BUILD''', '''ACTIVE''', '''PROCESSING''', '''SUSPENDED''', '''DELETED''', '''UNKNOWN'''
  
 
; hostId - ''string''
 
; hostId - ''string''
Line 118: Line 140:
 
; progress - ''number''
 
; 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.
 
: 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''
 
; metadata - ''object''
Line 130: Line 155:
 
; updated  
 
; updated  
 
: Unused always null.
 
: Unused always null.
 +
 +
; zone
 +
: Zone text key
  
 
==== addresses ====
 
==== addresses ====
Line 163: Line 191:
 
; flavor.id - ''string''
 
; flavor.id - ''string''
 
: Unique identifier for flavor this server is based on.
 
: Unique identifier for flavor this server is based on.
 +
 +
==== securityGroup ====
 +
; securityGroup.id - ''string''
 +
: the name of the security group that is assigned to this server
 +
 +
; securityGroup.links - ''list''
 +
: [[Hypermedia]] for the securityGroup.
  
 
== Response Codes ==
 
== Response Codes ==
Line 172: Line 207:
 
:''HTTP/1.1 400 Bad Request''
 
:''HTTP/1.1 400 Bad Request''
 
::The resource used for creating server is not found.
 
::The resource used for creating server is not found.
 +
 +
; Failure:
 +
:''HTTP/1.1 404 Bad Request''
 +
::The resource does not exist (when account number is not valid)
  
 
== Examples ==
 
== Examples ==
−
'''Create a new server'''
+
'''Successfully create a new server'''
−
:'''POST''' <nowiki>http://{api_url}/servers</nowiki>
+
:'''POST''' <nowiki>http://{api_server}/accounts/{accountId}/flexcloud/servers</nowiki>
  
 
''Request Headers:''
 
''Request Headers:''
Line 183: Line 222:
  
 
''Request Body:''
 
''Request Body:''
−
    {"server" : { "flavorRef" : "<nowiki>http://{server_name}//flavors/{flavor_id}</nowiki>", "name" : "{display_server_name}",  
+
<nowiki>
−
                  "imageRef" : "<nowiki>http://{server_name}//images/{image_id}</nowiki>" } }
+
{
−
 
+
    "server" :  
 +
      {
 +
          "flavorRef" : "http://{api_server}/accounts/{accountId}/flexcloud/flavors/1",
 +
          "securityGroupRef":"http://{server_name}/accounts/{accountId}/flexcloud/os-security-groups/{security_group_id}/",
 +
          "name" : "test_server_create",  
 +
          "imageRef" : "http://{api_server}/accounts/{accountId}/flexcloud/images/test_public_image",
 +
          "zone": "AUS001"
 +
      }
 +
} </nowiki>
 
''Response Code:''
 
''Response Code:''
 
<pre>HTTP/1.1 202 Accepted</pre>
 
<pre>HTTP/1.1 202 Accepted</pre>
  
 
''Response Body:''
 
''Response Body:''
−
    {"server": {"status": "BUILD", "updated": null, "hostId": "",  
+
<nowiki>
−
    "addresses": {"public": [{"version": 4, "addr": "{ip_address}"}], "private": [{"version": 4, "addr":  "{ip_address}"}]},  
+
{
−
    "links": [{"href": "<nowiki>http://{server_name}/servers/{server_id}/</nowiki>", "rel": "self"}], "image": {"name": "CentOS 5 Plesk",  
+
    "server":  
−
    "links": [{"href": "<nowiki>http://{server_name}/images/Centos%205%20x86%20Plesk/</nowiki>", "rel": "self"}], "id": "Centos 5 x86 Plesk"},  
+
      {
−
    "userId": "{user_account_id}", "flavor":  {"name": "", "links": [], "id": ""}, "id": "{server_id}", "name": "{display_server_name}",
+
          "status": "BUILD",  
−
    "created": "", "tenantId": null, "accessIPv4": "{ip_address}", "accessIPv6": null, "progress": 0, "metadata": {}}}
+
          "updated": null,  
 +
          "hostId": "",  
 +
          "addresses":  
 +
            {
 +
                "public": [
 +
                  {
 +
                      "version": 4,  
 +
                      "addr": "{ip_address}"
 +
                  }
 +
                ],
 +
                "private": [
 +
                  {
 +
                      "version": 4,  
 +
                      "addr":  "{ip_address}"
 +
                  }
 +
                ]
 +
            },  
 +
          "links": [
 +
            {
 +
                "href": "http://{api_server}/accounts/{accountId}/flexcloud/servers/167/",  
 +
                "rel": "self"
 +
            }
 +
          ],  
 +
          "imageRef":  
 +
            {
 +
                "name": "CentOS 5 Plesk",  
 +
                "links": [
 +
                  {
 +
                      "href": "http://{api_server}/accounts/{accountId}/flexcloud/images/test_public_image/",  
 +
                      "rel": "self"
 +
                  }
 +
                ],
 +
                "id": "test_public_image"
 +
          },  
 +
          "securityGroup":
 +
            {
 +
                "id":"group2012Nov02_jD6NX8BsK",
 +
                "links":[
 +
                  {
 +
                      "href":"http://{server_name}/accounts/{accountId}/flexcloud/os-security-groups/group2012Nov02_jD6NX8BsK/",
 +
                      "rel":"self"
 +
                  }
 +
                ],
 +
          },
 +
          "userId": "{user_account_id}",  
 +
          "flavorRef":   
 +
            {
 +
                "name": "",  
 +
                "links": [
 +
                  {
 +
                      "href": "http://{api_server}/accounts/{accountId}/flexcloud/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": {}
 +
      }
 +
}</nowiki>
  
−
* When a server is still pending (has not completed the provisioning process), the creation timestamp and hostId that are returned will be empty string.
+
* 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.
  
  
−
'''Create a server with bad request body'''
+
'''Failure while trying to create a server with a bad request body'''
−
:'''POST''' <nowiki>http://{api_url}/servers</nowiki>
+
:'''POST''' <nowiki>http://{api_server}/accounts/{accountId}/flexcloud/servers</nowiki>
  
 
''Request Headers:''
 
''Request Headers:''
Line 209: Line 323:
  
 
''Request Body:''
 
''Request Body:''
−
  {"server" : { "flavorRef" : "<nowiki>http://{server_name}//flavors/{flavor_id}</nowiki>", "name" : "{display_server_name}",  
+
<nowiki>
−
                  "imageRef" : "<nowiki>http://{server_name}//images/{image_id}</nowiki>" } }
+
  {
 +
    "server" :  
 +
      {  
 +
          "flavorRef" : "http://{api_server}/accounts/{accountId}/flexcloud/flavors/{flavor_id}",
 +
          "securityGroupRef" : "http://{api_server}/accounts/{accountId}/flexcloud/os-security-groups/{security_group_id}",
 +
          "name" : "{display_server_name}",
 +
          "imageRef" : "http://{api_server}/accounts/{accountId}/flexcloud/images/{fake_image_id}",
 +
          "zone": "AUS001"
 +
      }
 +
}</nowiki>
  
 
''Response Code:''
 
''Response Code:''
Line 216: Line 339:
  
 
''Response Body:''
 
''Response Body:''
−
  {"computeFault": {"message": "Bad imageRef", "code": 400, "details": ""}}
+
  <nowiki>
 +
{
 +
    "computeFault":  
 +
      {
 +
          "message": "Bad imageRef",  
 +
          "code": 400,  
 +
          "details": "",
 +
          "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
 +
      }
 +
}</nowiki>
  
 +
'''Failure while trying to pass invalid account number'''
 +
:'''POST''' http(s)://{api_server}/accounts/fake/flexcloud/servers
 +
 +
''Response Code:''
 +
<pre>HTTP/1.1 404 Not Found</pre>
 +
 +
''Response Body:''
 +
<nowiki>
 +
{
 +
    "itemNotFound" : {
 +
      "message": "Resource not found",
 +
      "code": 404,
 +
      "details": "",
 +
      "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
 +
    }
 +
}</nowiki>
  
−
<!--  THIS CODE ENABLES DISQUS COMMENTS ON THE PAGE - DELETE TO DISABLE COMMENTING-->
+
== Alternative URI /servers ==
 +
An alternative way to execute this call is to omit the ''accountId'' portion of the URI. In this case the system assumes the request is executed for the account identified in the [[Authentication|authorization header]].
  
−
{{#widget:DISQUS
+
<code>POST /servers</code>
−
|id=hostway
+
−
|uniqid={{PAGENAME}}
+
−
|url={{fullurl:{{PAGENAME}}}}
+
−
}}
+
  
−
<!--  ########################################################################### -->
+
[[Category:Hostway API]]
 +
[[Category:FlexCloud Server API]]

Latest revision as of 08:52, 15 September 2014

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.

Contents

[edit] POST /accounts/{accountId}/flexcloud/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.

[edit] Request

[edit] Request Parameters

accountId - string
The selected account Id.

[edit] JSON 

{
   "server":{
      "name":"{display_server_name}",
      "imageRef":"http://{server_name}/accounts/{accountId}/flexcloud/images/{image_id}/",
      "flavorRef":"http://{server_name}/accounts/{accountId}/flexcloud/flavors/{flavor_id}/",
      "securityGroupRef":"http://{server_name}/accounts/{accountId}/flexcloud/os-security-groups/{security_group_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
securityGroupRef - string
Absolute URL of the SecurityGroup to use
adminPass - string
Initial admin password. If not specified, the automatically generated password would be returned.
zone
Zone textkey

[edit] Result

[edit] 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}/accounts/{accountId}/flexcloud/servers/{server_id}/",
            "rel":"self"
         }
      ],
      "image":{
         "name":"{display_image_name}",
         "links":[
            {
               "href":"http://{server_name}/accounts/{accountId}/flexcloud/images/{image_id}/",
               "rel":"self"
            }
         ],
         "id":"{image_id}"
      },
      "securityGroup": {
         "id":"{security_group_id}",
         "links":[
            {
               "href":"http://{api_server}/accounts/{accountId}/flexcloud/os-security-groups/{security_group_id}/",
               "rel":"self"
            }
         ]
      },
      "userId":"{user_account_id}",
      "flavor":{
         "name":"{display_flavor_name}",
         "links":[
            {
               "href":"{server_name}/accounts/{accountId}/flexcloud/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.

[edit] server

id - string
Unique identifier for this server.
links - list
Hypermedia for this resource.
status - string
Current state of the server. Values: BUILD, ACTIVE, PROCESSING, 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

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

[edit] 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.

[edit] 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.

[edit] securityGroup

securityGroup.id - string
the name of the security group that is assigned to this server
securityGroup.links - list
Hypermedia for the securityGroup.

[edit] 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.
Failure
HTTP/1.1 404 Bad Request
The resource does not exist (when account number is not valid)

[edit] Examples

Successfully create a new server

POST http://{api_server}/accounts/{accountId}/flexcloud/servers

Request Headers: 

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

Request Body: 

 {
    "server" : 
       {
          "flavorRef" : "http://{api_server}/accounts/{accountId}/flexcloud/flavors/1",
          "securityGroupRef":"http://{server_name}/accounts/{accountId}/flexcloud/os-security-groups/{security_group_id}/",
          "name" : "test_server_create", 
          "imageRef" : "http://{api_server}/accounts/{accountId}/flexcloud/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}/accounts/{accountId}/flexcloud/servers/167/", 
                "rel": "self"
             }
          ], 
          "imageRef": 
             {
                "name": "CentOS 5 Plesk", 
                "links": [
                   {
                      "href": "http://{api_server}/accounts/{accountId}/flexcloud/images/test_public_image/", 
                      "rel": "self"
                   }
                ],
                "id": "test_public_image"
          }, 
          "securityGroup":
             {
                "id":"group2012Nov02_jD6NX8BsK",
                "links":[
                   {
                      "href":"http://{server_name}/accounts/{accountId}/flexcloud/os-security-groups/group2012Nov02_jD6NX8BsK/",
                      "rel":"self"
                   }
                ],
          },
          "userId": "{user_account_id}", 
          "flavorRef":  
             {
                "name": "", 
                "links": [
                   {
                      "href": "http://{api_server}/accounts/{accountId}/flexcloud/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}/accounts/{accountId}/flexcloud/servers

Request Headers: 

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

Request Body: 

 {
    "server" : 
       { 
          "flavorRef" : "http://{api_server}/accounts/{accountId}/flexcloud/flavors/{flavor_id}",
          "securityGroupRef" : "http://{api_server}/accounts/{accountId}/flexcloud/os-security-groups/{security_group_id}",
          "name" : "{display_server_name}",
          "imageRef" : "http://{api_server}/accounts/{accountId}/flexcloud/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"
       }
 }

Failure while trying to pass invalid account number

POST http(s)://{api_server}/accounts/fake/flexcloud/servers

Response Code: 

HTTP/1.1 404 Not Found

Response Body: 

 {
    "itemNotFound" : {
       "message": "Resource not found", 
       "code": 404, 
       "details": "",
       "errorid": "59e0b3dd-2173-432a-8ff5-60efe16e83bf"
    }
 }

[edit] Alternative URI /servers

An alternative way to execute this call is to omit the accountId portion of the URI. In this case the system assumes the request is executed for the account identified in the authorization header.

POST /servers

Retrieved from "http://docs.hostway.com/index.php?title=ServerCreate&oldid=1719"
Personal tools
Namespaces
Variants
Actions
APIs
Navigation
Toolbox