Skip to content

HTTP API v1

Jump to bottom
Frank Rosner edited this page Feb 20, 2018 · 22 revisions

Cluster Broccoli provides an RESTful HTTP API for managing templates and instances. The Web UI uses mostly the same protocol but through a WebSocket connection at /ws.

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",
      "cpu"
    ],
    "parameterInfos": {
      "cpu": {
        "name": "cpu",
        "default": "100"
      }
    },
    "version": "f88dbbdc8249b8e5075598e165aec527"
  },
  {
    "id": "jupyter",
    "description": "Open source, interactive data science and scientific computing across over 40 programming languages.",
    "parameters": [
      "id"
    ],
    "parameterInfos": {},
    "version": "2c64126e09b72abd1a46f6db5b296221"
  },
  {
    "id": "zeppelin",
    "description": "A web-based notebook that enables interactive data analytics. You can make beautiful data-driven, interactive and collaborative documents with SQL, Scala and more.",
    "parameters": [
      "id"
    ],
    "parameterInfos": {},
    "version": "6f983b4ea4e12344e73f450fa9201243"
  }
]

/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"
  ],
  "parameterInfos": {},
  "version": "2c64126e09b72abd1a46f6db5b296221"
}

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",
    "parameterValues": {
      "id": "my-http",
      "cpu": "250"
    },
    "status": "stopped",
    "services": [],
    "template": {
      "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",
        "cpu"
      ],
      "parameterInfos": {
        "cpu": {
          "name": "cpu",
          "default": "100"
        }
      },
      "version": "f88dbbdc8249b8e5075598e165aec527"
    }
  }
]

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", "cpu": "250" } }' \
  '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",
    "cpu": "250"
  },
  "status": "stopped",
  "services": [],
  "template": {
    "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",
      "cpu"
    ],
    "parameterInfos": {
      "cpu": {
        "name": "cpu",
        "default": "100"
      }
    },
    "version": "f88dbbdc8249b8e5075598e165aec527"
  }
}

/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'

Example return value:

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

{
  "id": "my-http",
  "parameterValues": {
    "id": "my-http",
    "cpu": "250"
  },
  "status": "stopped",
  "services": [],
  "template": {
    "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",
      "cpu"
    ],
    "parameterInfos": {
      "cpu": {
        "name": "cpu",
        "default": "100"
      }
    },
    "version": "f88dbbdc8249b8e5075598e165aec527"
  }
}

POST

Description: Updates an instance. You can either change the status, update the parameter values or select a new template of an instance.

Parameters: status, parameterValues, selectedTemplate, periodicJobsToStop.

Example query for status update:

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

Example query for parameter values update:

curl -v -H 'Content-Type: application/json' \
  -X POST -d '{ "parameterValues": { "id": "my-http", "cpu": "50" } }' \
  'http://localhost:9000/api/v1/instances/my-http'

Example query for periodic job stopping:

curl -v -H 'Content-Type: application/json' \
  -X POST -d '{ "periodicJobsToStop": ["my-curl/periodic-1518168960"] }' \
  'http://localhost:9000/api/v1/instances/my-curl'

Example return value:

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

{
  "id": "my-curl",
  "template": {
    "id": "curl",
    "description": "A periodic job that sends an HTTP GET request to a specified address every minute.",
    "parameters": [
      "id",
      "URL",
      "enabled"
    ],
    "parameterInfos": {
      "URL": {
        "id": "URL",
        "default": "localhost:8000",
        "type": "string"
      },
      "enabled": {
        "id": "enabled",
        "default": "true",
        "type": "raw"
      },
      "id": {
        "id": "id",
        "type": "string"
      }
    },
    "version": "300dd858eb5ac74be1f7779b94060df8"
  },
  "parameterValues": {
    "URL": "wttr.in",
    "id": "my-curl"
  },
  "status": "running",
  "services": [],
  "periodicRuns": [
    {
      "createdBy": "my-curl",
      "status": "dead",
      "utcSeconds": 1518168960,
      "jobName": "my-curl/periodic-1518168960"
    },
    {
      "createdBy": "my-curl",
      "status": "dead",
      "utcSeconds": 1518169020,
      "jobName": "my-curl/periodic-1518169020"
    },
    {
      "createdBy": "my-curl",
      "status": "dead",
      "utcSeconds": 1518169080,
      "jobName": "my-curl/periodic-1518169080"
    }
  ]
}

DELETE

Description: Stops and deletes an instance.

Parameters: None.

Example query:

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

Example return value:

< HTTP/1.1 200 OK

/api/v1/instances/<instanceId>/tasks

GET

Description: Gets the allocated tasks of an instance.

Parameters: None.

Example query:

curl -X GET 'localhost:9000/api/v1/instances/http-1/tasks'

Example return value:

< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "name": "http-task",
    "allocations": [
      {
        "id": "47986b51-88d7-eed6-7796-aec27bbf1953",
        "clientStatus": "running",
        "taskState": "running"
      }
    ]
  }
]

Authentication

/api/v1/auth/login

The login endpoint can be used to obtain a session cookie.

POST

Description: Provides a session cookie on successful authentication.

Parameters: username, password (as form data)

Example query:

curl -v -XPOST -F 'username=user' -F 'password=secret' \
  'localhost:9000/api/v1/auth/login'

Example return value:

< HTTP/1.1 200 OK
< Set-Cookie: BROCCOLI_SESS_ID=031685079e88a3562935dc58e39d3b8da3f2ea650xsb2mf_42tm6x1o)7'c.6elirxy89i390yg3xv~8i3aox8mg8kxnhu(acr'25tc; Max-Age=3600; Expires=Sat, 12 Nov 2016 17:13:34 GMT; Path=/; HTTPOnly

/api/v1/auth/logout

The logout endpoint can be used to invalidate your session.

POST

Description: Invalidates your session (logout).

Parameters: BROCCOLI_SESS_ID (as cookie)

Example query:

curl -v -XPOST --cookie "BROCCOLI_SESS_ID=031685079e88a3562935dc58e39d3b8da3f2ea650xsb2mf_42tm6x1o)7'c.6elirxy89i390yg3xv~8i3aox8mg8kxnhu(acr'25tc" \
'localhost:9000/api/v1/auth/logout'

Example return value:

< HTTP/1.1 200 OK
< Set-Cookie: BROCCOLI_SESS_ID=; Max-Age=-86400; Expires=Fri, 11 Nov 2016 16:46:13 GMT; Path=/; HTTPOnly

/api/v1/auth/verify

The verify endpoint can be used to check whether your session is still active. If you are logged in it will return your username. If authentication is disabled it will return "anoynmous".

GET

Description: Checks whether your session is still valid.

Parameters: BROCCOLI_SESS_ID (as cookie)

Example query:

curl -v --cookie "BROCCOLI_SESS_ID=031685079e88a3562935dc58e39d3b8da3f2ea650xsb2mf_42tm6x1o)7'c.6elirxy89i390yg3xv~8i3aox8mg8kxnhu(acr'25tc" \
'localhost:9000/api/v1/auth/verify'

Example return value:

< HTTP/1.1 200 OK
< Set-Cookie: BROCCOLI_SESS_ID=031685079e88a3562935dc58e39d3b8da3f2ea650xsb2mf_42tm6x1o)7'c.6elirxy89i390yg3xv~8i3aox8mg8kxnhu(acr'25tc; Max-Age=3600; Expires=Sat, 12 Nov 2016 17:53:14 GMT; Path=/; HTTPOnly
< Content-Type: text/plain; charset=utf-8

frank

About

/api/v1/about

You can query the about endpoint to get some information about your Broccoli deployment.

GET

Description: Returns information about Cluster Broccoli.

Example query:

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

Example return value:

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

{
  "services": {
    "clusterManager": {
      "connected": true
    },
    "serviceDiscovery": {
      "connected": false
    }
  },
  "auth": {
    "enabled": false,
    "user": {
      "name": "anonymous",
      "role": "administrator",
      "instanceRegex": ".*"
    }
  },
  "project": {
    "name": "Cluster Broccoli",
    "version": "0.6.0-SNAPSHOT"
  },
  "sbt": {
    "version": "0.13.11"
  },
  "scala": {
    "version": "2.10.6"
  }
}

Log Download

/downloads/instances/<instanceId>/allocations/<allocId>/tasks/<taskName>/logs/

This endpoint can be used to get task logs for job runs of instances.

GET

Description: Returns task logs of specified allocation and task. You can specify an offset to only get the latest logs.

Parameters: offset (optional).

Example query:

curl -v "localhost:9000/downloads/instances/test-http/allocations/400c652b-8427-2c7e-54dc-93ced0fbc536/tasks/http-task/logs/stdout\?offset\=500KiB"

Example return value:

< HTTP/1.1 200 OK
< Content-Type: text/plain; charset=utf-8

Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8080
  http://172.27.5.240:8080
Hit CTRL-C to stop the server

/downloads/instances/<instanceId>/periodic/<periodicJobId>/allocations/<allocId>/tasks/<taskName>/logs/

This endpoint can be used to get task logs for job runs of instances.

GET

Description: Returns task logs of specified periodic allocation and task. You can specify an offset to only get the latest logs.

Parameters: offset (optional).

Example query:

curl -v "localhost:9000/downloads/instances/my-curl/periodic/my-curl/periodic-1519120980/allocations/bcb6ab42-a2cb-2209-f2b4-873564bf678e/tasks/curl-task/logs/stdout?offset=500KiB"

Example return value:

< HTTP/1.1 200 OK
< Content-Type: text/plain; charset=utf-8

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html>
<title>Directory listing for /</title>
<body>
<h2>Directory listing for /</h2>
<hr>
<ul>
<li><a href="executor.out">executor.out</a>
<li><a href="local/">local/</a>
<li><a href="secrets/">secrets/</a>
<li><a href="tmp/">tmp/</a>
</ul>
<hr>
</body>
</html>
Clone this wiki locally