REST API

Cloudsoft AMP 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.2.0-SNAPSHOT

And in the REST API it is accessed at:

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 AMP 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 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)