Working with the Compose API

The API in context

The Compose API is a RESTful API with authorization managed by personal access tokens. As such it is made up of a number of REST endpoints which handle different aspects of the Compose service.

At the heart of the API is the concept of accounts. An account is owned by a user but can also have other users associated with it with different privilege levels as to what they can do with an account. To use the API, a personal access token associated with the account and the user that generated it. Details on how to obtain the token can be found in Authorization and how to get it.

Through the API it is possible to create database deployments. These are complete, self-contained databases which can be accessed through their own clients and APIs depending on the type of database. Deployments are associated with the account used to create them. There are a number of types of database deployment, such as "mongodb", "postgresql" and "redis" . The type is specified at the creation of a deployment.

Also specified at creation is where the deployment will reside. Deployments generally reside in datacenters where they are hosted and managed by Compose. Deployments can also reside in specific clusters which are created for enterprise customers for their exclusive use - these clusters are associated with a particular account too.

Whenever a deployment is created or has some other operation performed like a version change or an additional feature added, that operation is performed using a recipe. A deployment retains a complete history of the recipes that have been applied to it over its lifetime. A recipe can take some time to run. If you have the id of a recipe, you can ask the API for the current progress and status of that recipe.

Practical API use

Creating a deployment involves:

  • Obtaining a personal access token - Authorization and how to get it

  • Obtaining via the API the account id of the account the personal access token is associated with - Accounts

  • Obtaining the list of database types and versions available and selecting one that is appropriate - Types and /2016-07/databases

  • Obtaining the list of datacenters available - Datacenters and /2016-07/datacenters

  • Creating a JSON document for the settings of the new deployment. This must include at least the account id, name, datacenter, and type for the new database - /2016-07/deployments

  • POSTing the JSON document to the deployments endpoint and saving the JSON response from that endpoint. The response will include a recipe id for the creation of the deployment.

  • Poll the recipe endpoint until it completes - /2016-07/get-recipes/:id

What’s Next