guide/ops/rest.md

---
title: REST API
layout: website-normal
---

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:

<!-- BROOKLYN_VERSION_BELOW -->
    http://localhost:8081/#v1/catalog/entities/cluster:1.2.0-SNAPSHOT

And in the REST API it is accessed at:

<!-- BROOKLYN_VERSION_BELOW -->
    http://localhost:8081/v1/catalog/entities/cluster:1.2.0-SNAPSHOT

A full reference for the REST API is automatically generated by the server at runtime.
It can be found in the Brooklyn web console by clicking `REST API` under the menu icon in the top right corner.
This opens a Swagger UI that allows users to see the full reference for the API capabilities, as well as
execute the API commands with a user-friendly interface.

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](https://stedolan.github.io/jq/)
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`)