Machine Management REST API

Contents

1. Introduction

This document describes the REST API provided by GATE Cloud to monitor and control cloud machines that you have purchased (either through the website or via the shop API).

2. List all machines

GET https://cloud.gate.ac.uk/api/machine

Request a summary of all machines owned by the authenticating user, optionally filtered by state

Query string parameters

  • state (optional) show only machines in a particular state or states. There are five possible states, two "steady" states active (up and running) and inactive (stopped), two "transition" states pending (in the process of starting up) and stopping (in the process of shutting down), and the "destroyed" state for machines that have been deleted and the record is kept for archive purposes only. If omitted, all non-destroyed machines are returned.

Example: https://cloud.gate.ac.uk/api/machine?state=active&state=stopping would list machines that are either running or shutting down.

Response format

XML JSON 
<machines>
  <machine>
    <id>14</id>
    <url>https://cloud.gate.ac.uk/api/machine/14</url>
    <state>inactive</state>
  </machine>
  ...
</machines>

[
  {
    "id":14,
    "url":"https://cloud.gate.ac.uk/api/machine/14",
    "state":"inactive"
  },
  ...
]

The url can be queried to get more details about a specific machine.

3. Machine details

3.1. Query machine details

GET https://cloud.gate.ac.uk/api/machine/{id}

Get the details of a specific machine including its name, type, cost, etc.

Response format

XML JSON 
<machine>
  <key>value</key>
  ...
</machine>

{
  "key":"value",
  ...
}
Key Value
id The machine identifier
name The machine name
state

The current machine state (active, inactive, etc., see above)

hourlyPrice Price per hour that this machine will cost when it is running
lastTransition Date and time of the last state transition (inactive to pending, pending to active, etc.)
publicUrl (only included if state is "active") Public URL at which this machine's web-facing services can be accessed, typically of the form https://{something}.services.gate.ac.uk
kind The type of machine - twitterCollector, teamware or mimir
adminPassword The original admin password that was generated for this machine when it was reserved. GATE Cloud can only know the original generated password, it may not be current if you have changed the password yourself subsequently.

3.2. Update machine details

POST https://cloud.gate.ac.uk/api/machine/{id}

Modify the machine details. Currently the only modifiable "detail" is the machine name.

Request format

XML JSON 
<machine>
  <name>New name</name>
</machine>

{
  "name":"New name"
}

Response

Exactly as for the GET case above.

4. Controlling a machine

POST https://cloud.gate.ac.uk/api/machine/{id}/control

This URL is the interface through which you can start an inactive machine or stop an active one.

Request format

XML JSON 
<control>
  <action>{value}</action>
</control>

{
  "action":"{value}",
}

Supported actions

Action Valid state Effect
start inactive Start a machine running
stop active Shut down a running machine

If the request is successful, a 204 (no content) HTTP response is returned.