
REST Endpoints
**************


Cluster
=======

**Endpoint**: /api/v0/cluster/{NAME}


GET
---

Retrieve the status of the cluster.

   {
       "status" string,
       "hosts": {
           "total": int,
           "available": int,
           "unavailable": int
       }
   }


Example
~~~~~~~

   {
       "status": "ok",
       "hosts": {
           "total": 3,
           "available": 3,
           "unavailable": 0
       }
   }


PUT
---

Creates a new cluster.

No body.


Cluster Members
===============

**Endpoint**: /api/v0/cluster/{NAME}/hosts


GET
---

Retrieve the host list for a cluster.

   [
       host_address,...
   ]


Example
~~~~~~~

   [
       "192.168.100.50",
       "192.168.100.51"
   ]


PUT
---

Replace the host list for a cluster.  The "old" list must match the
current host list.

   {
       "old": [host_address,...]
       "new": [host_address,...]
   }


Example
~~~~~~~

   {
       "old": ["192.168.100.50"],
       "new": ["192.168.100.50", "192.168.100.51"]
   }


Cluster Members (Individual)
============================

**Endpoint**: /api/v0/cluster/{NAME}/hosts/{IP}


GET
---

Membership test.  Returns 200 if host {IP} is in cluster, else 404.


PUT
---

Adds host {IP} to cluster. (Idempotent)

No body.


DELETE
------

Removes host {IP} from cluster. (Idempotent)

No body.


Cluster Operations: Upgrade
===========================

**Endpoint**: /api/v0/cluster/{NAME}/upgrade


GET
---

Retrieve the current status of upgrades.

   {
       "status": string,
       "upgrade_to": string,
       "upgraded": HOST_LIST,
       "in_process": HOST_LIST,
       "started_at": string,
       "finished_at": string
   }


Example
~~~~~~~

   {
       "status": "in_process",
       "upgrade_to": "7.2.1",
       "upgraded": [{...}],
       "in_process": [{...}],
       "started_at": "2015-12-17T15:48:18.710454",
       "finished_at": null
   }


PUT
---

Start a new upgrade.

   {
       "upgrade_to": string
   }


Example
~~~~~~~

   {
       "upgrade_to": "7.2.1"
   }


Example Response
~~~~~~~~~~~~~~~~

   {
       "status": "in_process",
       "upgrade_to": "7.2.1",
       "upgraded": [{...}],
       "in_process": [{...}],
       "started_at": "2015-12-17T15:48:18.710454",
       "finished_at": null
   }


Cluster Operations: Restart
===========================

**Endpoint**: /api/v0/cluster/{NAME}/restart


GET
---

Retrieve the status of a restart.

   {
       "status": string,
       "restarted": HOST_LIST,
       "in_process": HOST_LIST,
       "started_at": string,
       "finished_at": string
   }


Example
~~~~~~~

   {
       "status": "in_process",
       "restarted": [{...}],
       "in_process": [{...}],
       "started_at": "2015-12-17T15:48:18.710454",
       "finished_at": null
   }


PUT
---

Create a new restart.

No body.


Example Response
~~~~~~~~~~~~~~~~

   {
      "status": "in_process", "restarted": [{...}], "in_process":
      [{...}], "started_at": "2015-12-17T15:48:18.710454",
      "finished_at": null

   }


Clusters
========

**Endpoint**: /api/v0/cluster/


GET
---

Retrieve a list of all clusters.

   [
       string,...
   ]


Example
~~~~~~~

   [
      "mycluster",
   ]


Host
====

**Endpoint**: /api/v0/host/{IP}


GET
---

Retrieve a specific host record.

   {
       "address": string,       // The IP address of the cluster host
       "status":  enum(string), // The status of the cluster host
       "os": enum(string),      // The OS name
       "cpus": int,             // The number of CPUs on the cluster host
       "memory": int,           // The memory of the cluster host in kilobytes
       "space": int,            // The diskspace on the cluster host
       "last_check": string     // ISO date format the cluster host was last checked
   }

Note: See Host Statuses for a list and description of host statuses.

Note: See OS's for a list and description of host statuses.


Example
~~~~~~~

   {
       "address": "192.168.100.50",
       "status": "active",
       "os": "atomic",
       "cpus": 4,
       "memory": 11989228,
       "space": 487652,
       "last_check": "2015-12-17T15:48:18.710454"
   }


PUT
---

Creates a new host record.

   {
       "ssh_priv_key": string // base64 encoded ssh private key
       "cluster": string      // Optional cluster the host should be associated with
   }

Note: The rest of the host record will be filled out once the data
  has been pulled from the cluster host.

Note: As a convenience to hosts wishing to add themselves as part of
  a boot script, the endpoint /api/v0/host (without the {IP}) also
  accepts PUT requests.  Here, the host address is inferred from the
  request itself but otherwise works the same: creates a new host
  record accessible at /api/v0/host/{IP}.


Example
~~~~~~~

   {
       "cluster": "default",
       "ssh_priv_key": "dGVzdAo..."
   }


DELETE
------

Deletes a host record.


Hosts
=====

**Endpoint**: /api/v0/clusters


GET
---

Retrieve a list of clusters.

   [
       string...
   ]


Example
~~~~~~~

   [
       "development",
       "production"
   ]

**Endpoint**: /api/v0/hosts


GET
---

Retrieve a list of hosts.

   [
       {
           "address": string,       // The IP address of the cluster host
           "status":  enum(string), // The status of the cluster host
           "os": enum(string),      // The OS name
           "cpus": int,             // The number of CPUs on the cluster host
           "memory": int,           // The memory of the cluster host in kilobytes
           "space": int,            // The diskspace on the cluster host
           "last_check": string     // ISO date format the cluster host was last checked
       }...
   ]

Note: See Host Statuses for a list and description of host statuses.

Note: See OS's for a list and description of host statuses.


Example
~~~~~~~

   [
       {
           "address": "192.168.100.50",
           "status": "active",
           "os": "atomic",
           "cpus": 4,
           "memory": 11989228,
           "space": 487652,
           "last_check": "2015-12-17T15:48:18.710454"
       },
       {
           "address": "192.168.100.51",
           "status": "active",
           "os": "atomic",
           "cpus": 3,
           "memory": 11989228,
           "space": 487652,
           "last_check": "2015-12-17T15:48:30.401090"
       }
   ]


Status
======

**Endpoint**: /api/v0/status


GET
---

Retrieve a the status of the system.

   {
       "etcd": {
           "status": enum(string),      // Status of etcd connection
       },
       "investigator": {
           "status": enum(string),      // Status of the investigator pool
           "info": {
               "size": int,             // Total size of the investigator pool
               "in_use": int,           // Amount of the pool in use
               "errors": [string,...],  // Errors from the pool
           },
       },
   }

Note: See Status Statuses for a list and description of status
  statuses.


Example
~~~~~~~

   {
       "etcd": {
           "status": "OK"
       },
       "investigator": {
           "status": "OK",
           "info": {
               "size": 1,
               "in_use": 1,
               "errors": []
           }
       }
   }
