-
Notifications
You must be signed in to change notification settings - Fork 22
HTTP API v1
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.
A template defines the structure of a Nomad job. It consists of an ID, a description, the Nomad job JSON template including variable parameters.
The general templates endpoint is used to query existing templates. Templates are read-only and will be loaded on application start-up.
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"
}
]The specific templates endpoint is used to get more detailed information about a template.
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"
}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.
The general instances endpoint is used to get all created instances, as well as creating new instances.
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"
}
}
]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"
}
}The specific instances endpoint is used to get details about, change the status of and delete single instances.
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"
}
}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.
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 return value for status update:
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
{
"id": "my-http",
"parameterValues": {
"id": "my-http",
"cpu": "250"
},
"status": "pending",
"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"
}
}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 return value for parameter values update:
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
{
"id": "my-http",
"parameterValues": {
"id": "my-http",
"cpu": "50"
},
"status": "pending",
"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"
}
}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
The login endpoint can be used to obtain a session cookie.
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
The logout endpoint can be used to invalidate your session.
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
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".
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
You can query the about endpoint to get some information about your Broccoli deployment.
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"
}
}