The Command Line

Using the command line is a useful option when exploring the Compose API and when you wish to embed API access into a shell script.

For each endpoint in the Compose API reference pages, we show an appropriate [curl]((https://curl.haxx.se/) command which will invoke that endpoint. If we take the deployments endpoint, the reference page looks like this:

The essential part of this information is the Shell command:

curl -X GET -H "Authorization: Bearer [[app:Authorization]]" -H "Content-Type: application/hal+json" 'https://api.compose.io/2016-07/deployments'

If we run that command as is, you'll get an error back:

{"errors":"invalid_token"}

Any call on the API needs a personal API token to use this command. Read Authorization and how to get it to obtain your token. The token will be a long string of hexadecimal digits which you will need to keep safe. Do not embed it in code or scripts as these may be checked in to source code control systems and give others access. For example, keep it in an environment variable and refer to the variable, not the actual value:

export COMPOSEAPITOKEN=7145586d604b735164f83af7f69227b14989085ce067e6db9235d6de1ef87808

The environment variable can then be substituted into the command automatically by replacing the [[app:Authorization]] section like so:

curl -X GET -H "Authorization: Bearer $COMPOSEAPITOKEN" -H "Content-Type: application/hal+json" 'https://api.compose.io/2016-07/deployments'

This command will output all the deployments, but with little formatting. If you wish to format the output, add -s to the the curl command and pipe the output to python -m json.tool which will format the output.

curl -s -X GET -H "Authorization: Bearer $COMPOSEAPITOKEN" -H "Content-Type: application/hal+json" 'https://api.compose.io/2016-07/deployments'  | python -m json.tool

If you want to syntax-highlight the output use the [jq](https://stedolan.github.io/jq/) application which will also give you options to parse the data and manipulate it. For example, the following command will get the deployments data and then return an array of JSON objects with just the name and deployment id.

curl -s -X GET -H "Authorization: Bearer $COMPOSEAPITOKEN" -H "Content-Type: application/hal+json" 'https://api.compose.io/2016-07/deployments'  | jq "[{id:._embedded.deployments[].id,name:._embedded.deployments[].name}]"

Other utilities for processing the returned JSON are available.