Server examples
Create a cloud server, then start it, stop it, or cancel it. API v2.10.
Overview
Post JSON to https://api.rackcorp.net/api/rest/v2.10/json.php with Authorization: Bearer.
A success response has code OK. Result fields sit next to code.
The Device API reads a server after it exists. Creating one, and turning it on or off, uses the calls on this page.
A billed cloud server is an order. order.create.server stores the order.
order.confirm.server places the contract and provisioning starts.
Start, stop, and cancel are rctransaction.create calls against the device id that provisioning assigns.
| Action | Command | type |
|---|---|---|
| Create | order.create.server, then order.confirm.server | |
| Start | rctransaction.create | STARTUP |
| Stop (guest shutdown) | rctransaction.create | SAFESHUTDOWN |
| Stop (immediate) | rctransaction.create | SHUTDOWN |
| Force power off | rctransaction.create | FORCESHUTDOWN (confirm) |
| Restart | rctransaction.create | RESTART |
| Cancel the server | rctransaction.create | CANCEL (confirm) |
1. Choose a datacentre and an operating system
dc.getall with tagname VIRTUALSERVER returns dcs.
Use dcId as productdetails.DCID.
product.os.get with status ACTIVE returns os.
Use billabletagname as productdetails.OS.
{
"cmd": "dc.getall",
"tagname": "VIRTUALSERVER"
}{
"cmd": "product.os.get",
"status": "ACTIVE"
}
Network, backup, and support options are catalogue tags.
product.serviceplan.get with name SERVER and groupby groupname returns billabletagname values.
The create example below uses the same defaults as the portal order form.
2. Create the order
customerid is the account the server is billed to, and it must sit in the caller's customer tree.
CPU, MEMORYGB, and STORAGEGB are integers of at least 1.
NOINSTANCES is how many servers this order creates. Each one comes back as its own contract id.
TRAFFICGB is required unless NT-SPEED contains UNMETERED.
Replace DCID, OS, and the NT-SPEED, TRAFFICGB, BKP, and SUPPORT tags with values from the lookup calls. The tags in the sample are the portal order-form defaults.
For a private cloud host you own, set CLOUDTYPE to private and VMHID to that host's device id.
{
"cmd": "order.create.server",
"customerid": 1234,
"currency": "AUD",
"servicebilltag": "CLOUDSERVER",
"productdetails": {
"CLOUDTYPE": "public",
"DCID": 4,
"HOSTNAME": "app-01.example.com",
"CPU": 2,
"MEMORYGB": 4,
"STORAGEGB": 40,
"OS": "OS-UBUNTU2204",
"NOINSTANCES": 1,
"IPV4": 1,
"NT-SPEED": "NT-SPEED100",
"TRAFFICGB": "TRAFFICGB-100",
"BKP": "BKP-FREE",
"SUPPORT": "SUPPORT-STD"
}
}REST: POST /api/rest/v2.10/order/create/server with the same JSON body, without cmd.
curl -X POST "https://api.rackcorp.net/api/rest/v2.10/json.php" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"cmd":"order.create.server","customerid":1234,"currency":"AUD","servicebilltag":"CLOUDSERVER","productdetails":{"CLOUDTYPE":"public","DCID":4,"HOSTNAME":"app-01.example.com","CPU":2,"MEMORYGB":4,"STORAGEGB":40,"OS":"OS-UBUNTU2204","NOINSTANCES":1,"IPV4":1,"NT-SPEED":"NT-SPEED100","TRAFFICGB":"TRAFFICGB-100","BKP":"BKP-FREE","SUPPORT":"SUPPORT-STD"}}'A success response includes order.orderid and order.currency. Keep orderid for the confirm call. An account that must prepay and has no credit is rejected here.
{
"code": "OK",
"message": "Order created",
"order": {
"orderid": 12345,
"currency": "AUD"
}
}3. Confirm the order
Confirm places the contract and starts provisioning. The server is billed from this point. Leave the order unconfirmed if you do not want the server created.
{
"cmd": "order.confirm.server",
"id": 12345
}REST: GET /api/rest/v2.10/order/confirm/server/12345.
contractsid is one contract id per instance. Provisioning is asynchronous, so the device id is empty until the builder finishes.
{
"code": "OK",
"message": "Order confirmed",
"contractsid": [67890]
}4. Wait for the device id
order.contract.get returns contract.
status stays PENDING until deviceID is set, then status is ACTIVE.
Poll until deviceID is present. That id is objId on every power call below.
device.get with that id returns operationalStatus (RUNNING or STOPPED). Power status can lag by about a minute.
{
"cmd": "order.contract.get",
"contractId": 67890
}5. Start
objType is DEVICE. objId is the device id.
type STARTUP queues a power-on. The same call with RESTART reboots the server.
The response field rcTransaction.method echoes the type.
rctransaction.get with rcTransactionId returns status (PENDING, then COMMENCED, then COMPLETED or FAILED).
{
"cmd": "rctransaction.create",
"objType": "DEVICE",
"objId": 555,
"type": "STARTUP"
}REST: POST /api/rest/v2.10/rctransaction with the same body, without cmd.
{
"code": "OK",
"message": "Transaction successfully created",
"rcTransaction": {
"rcTransactionId": 9001,
"objType": "DEVICE",
"objId": 555,
"method": "STARTUP",
"confirmationRequired": false,
"confirmationText": ""
}
}6. Stop
SAFESHUTDOWN asks the guest to shut down. That is the portal safe shutdown.
SHUTDOWN powers the server off immediately.
Both queue on the first call.
{
"cmd": "rctransaction.create",
"objType": "DEVICE",
"objId": 555,
"type": "SAFESHUTDOWN"
}
FORCESHUTDOWN is a hard power-off and needs a second call.
The first response has confirmationRequired true and confirmationText, and nothing is queued.
Send the same request again with confirmation true. The second response has confirmationRequired false and an rcTransactionId.
{
"cmd": "rctransaction.create",
"objType": "DEVICE",
"objId": 555,
"type": "FORCESHUTDOWN",
"confirmation": true
}7. Cancel the server
type CANCEL deletes the server and its data. This cannot be undone.
The first call returns confirmationRequired true and the warning in confirmationText. That response does not queue the delete.
Repeat the call with confirmation true to queue it.
code OK on the first response means the warning was returned. The delete is queued only when the second response has confirmationRequired false and an rcTransactionId.
{
"cmd": "rctransaction.create",
"objType": "DEVICE",
"objId": 555,
"type": "CANCEL"
}{
"cmd": "rctransaction.create",
"objType": "DEVICE",
"objId": 555,
"type": "CANCEL",
"confirmation": true
}
Cancelling the server uses type CANCEL on rctransaction.create.
rctransaction.cancel is a different command and does not delete a server.