Skip to content

HTTP API v1

Jump to bottom
Frank Rosner edited this page Jun 24, 2016 · 22 revisions

Cluster Broccoli provides an RESTful HTTP API for managing templates and instances. It is also used by the Web UI, which utilizes Restangular to submit the API calls.

There are two nouns in Cluster Broccoli: Templates and instances. A template is used to spawn new instances replacing variables with specified values. An instance has a status and a set of services. Cluster Broccoli queries Nomad for getting the status of an instance, while using Consul for discovering services associated with it.

Table of Contents

Templates

A template defines the structure of a Nomad job. It consists of an ID, a description, the Nomad job JSON template including variable parameters.

/api/v1/templates

The general templates endpoint is used to query existing templates. Templates are read-only and will be loaded on application start-up.

GET

Description: Lists all available templates.

Parameters: None.

Example query:

curl 'localhost:9000/api/v1/templates'

Example return value:

< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8

[
  {
    "id": "http-server",
    "description": "A simple Python HTTP request handler. This class serves files from the current directory and below, directly mapping the directory structure to HTTP requests.",
    "parameters": [
      "id"
    ]
  },
  {
    "id": "jupyter",
    "description": "Open source, interactive data science and scientific computing across over 40 programming languages.",
    "parameters": [
      "id"
    ]
  },
  {
    "id": "zeppelin",
    "description": "A web-based notebook that enables interactive data analytics.\nYou can make beautiful data-driven, interactive and collaborative documents with SQL, Scala and more.",
    "parameters": [
      "id"
    ]
  }
]

/api/v1/templates/<templateId>

The specific templates endpoint is used to get more detailed information about a template.

GET

Description: Queries a single template.

Parameters: None.

Example query:

curl 'localhost:9000/api/v1/templates/jupyter'

Example return value:

< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8

{
  "id": "jupyter",
  "description": "Open source, interactive data science and scientific computing across over 40 programming languages.",
  "parameters": [
    "id"
  ]
}

Instances

An instance represents a template with all parameter values being set. It is used to submit a Nomad job to the cluster. It consists of an ID, the template it is derived from, a parameter value mapping, a status, and a set of services.

/api/v1/instances

The general instances endpoint is used to get all created instances, as well as creating new instances.

GET

Description: Lists all created instances.

Parameters: templateId (optional).

Example query:

curl 'localhost:9000/api/v1/instances?templateId=http-server'

Example return value:

< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8

[
  {
    "id": "my-http-server",
    "parameterValues": {
      "id": "my-http-server"
    },
    "status": "running",
    "services": {
      "my-http-server-web-ui": {
        "name": "my-http-server-web-ui",
        "protocol": "http",
        "address": "127.0.0.1",
        "port": 8000
      }
    }
  },
  {
    "id": "my-http",
    "parameterValues": {
      "id": "my-http"
    },
    "status": "stopped",
    "services": {}
  }
]

POST

Description: Creates a new instance.

Parameters: Creation request JSON (templateId, parameters).

Example query:

curl -H 'Content-Type: application/json' \
  -X POST -d '{ "templateId": "http-server", "parameters": { "id": "my-http" } }' \
  'http://localhost:9000/api/v1/instances'

Example return value:

< HTTP/1.1 201 Created
< Location: /api/v1/instances/my-http
< Content-Type: application/json; charset=utf-8

{
  "id": "my-http",
  "parameterValues": {
    "id": "my-http"
  },
  "status": "stopped",
  "services": {}
}

/api/v1/instances/<instanceId>

The specific instances endpoint is used to get details about, change the status of and delete single instances.

GET

Description: Queries a single instance.

Parameters: None.

Example query:

curl 'localhost:9000/api/v1/instances/my-http-server'

Example return value:

< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8

{
  "id": "my-http-server",
  "parameterValues": {
    "id": "my-http-server"
  },
  "status": "running",
  "services": {
    "my-http-server-web-ui": {
      "name": "my-http-server-web-ui",
      "protocol": "http",
      "address": "127.0.0.1",
      "port": 8000
    }
  }
}

POST

Description: Sends a status update request to an instance.

Parameters: desiredStatus.

Example query:

curl -H 'Content-Type: application/json' \
  -X POST -d '"running"' \
  'http://localhost:9000/api/v1/instances/my-http-server'

Example return value:

< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8

{
  "id": "my-http-server",
  "parameterValues": {
    "id": "my-http-server"
  },
  "status": "pending",
  "services": {
    "my-http-server-web-ui": {
      "name": "my-http-server-web-ui",
      "protocol": "http",
      "address": "127.0.0.1",
      "port": 8000
    }
  }
}

DELETE

Description: Stops and deletes an instance.

Parameters: None.

Example query:

curl -X DELETE 'localhost:9000/api/v1/instances/my-http-server'

Example return value:

< HTTP/1.1 200 OK
Clone this wiki locally