REST API

Apache Brooklyn exposes a powerful REST API, allowing it to be scripted from bash or integrated with other systems.

For many commands, the REST call follows the same structure as the web console URL scheme, but with the # at the start of the path removed; for instance the catalog item cluster in the web console is displayed at:

http://localhost:8081/#v1/catalog/entities/cluster:1.0.0-M1

And in the REST API it is accessed at:

http://localhost:8081/v1/catalog/entities/cluster:1.0.0-M1

A full reference for the REST API is automatically generated by the server at runtime. It can be found in the Brooklyn web console, under the Script tab.

Here we include some of the most common REST examples and other advice for working with the REST API.

Tooling Tips

For command-line access, we recommend curl, with tips below.

For navigating in a browser we recommend getting a plugin for working with REST; these are available for most browsers and make it easier to authenticate, set headers, and see JSON responses.

For manipulating JSON responses on the command-line, the library jq from stedolan's github is very useful, and available in most package repositories, including port and brew on Mac.

Common REST Examples

Here are some useful snippets:

• List applications

  curl http://localhost:8081/v1/applications
  

• Deploy an application from __FILE__

  curl http://localhost:8081/v1/applications --data-binary @__FILE__
  

• Get details of a task with ID __ID__ (where the id is returned by the above, optionally piped to jq .id)

  curl http://localhost:8081/v1/activities/__ID__
  

• Get the value of sensor service.state on entity e1 in application app1 (note you can use either the entity's ID or its name)

  curl http://localhost:8081/v1/applications/app1/entities/e1/sensors/service.state
  

• Get all sensor values (using the pseudo-sensor current-state)

  curl http://localhost:8081/v1/applications/app1/entities/e1/sensors/service.state
  

• Invoke an effector eff on e1, with argument arg1 equal to hi (note if no arguments, you must specify -d ""; for multiple args, just use multiple -d entries, or a JSON file with --data-binary @...)

  curl http://localhost:8081/v1/applications/app1/entities/e1/effectors/eff -d arg1=hi
  

• Add an item to the catalog from __FILE__

  curl http://localhost:8081/v1/catalog --data-binary @__FILE__
  

Curl Cheat Sheet

• if authentication is required, use --user username:password
• to see detailed output, including headers, code, and errors, use -v
• where the request is not a simple HTTP GET, use -X POST or -X DELETE
• to pass key-value data to a post, use -d key=value
• where you are posting from a file __FILE__, use --data-binary @__FILE__ (implies a POST) or -T __FILE__ -X POST
• to add a header, use -H "key: value", for example -H "Brooklyn-Allow-Non-Master-Access: true"
• to specify that a specific content-type is being uploaded, use -H "Content-Type: application/json" (or application/yaml)
• to specify the content-type required for the result, use -H "Accept: application/json" (or application/yaml, or for sensor values, text/plain)