Skip to content

Get started with the REST API

Every madbot instance serves a REST API. The web client uses it, and so can your scripts. The reference describes each endpoint for the latest release of madbot-api. This page explains what all the endpoints have in common, then runs a first script.

A script authenticates with a personal access token, created in the web client:

  1. Open the user menu, then Account settings, then Tokens.
  2. Select Create a new token, name it and choose its scopes:
    • read: read the resources;
    • write: create, change and delete them;
    • *: full access, alone.
  3. Copy the token. It starts with pat_, and the web client shows it only once.

Send it in the Authorization header of each request:

Authorization: Bearer pat_…

The account of the token must be approved by an administrator of the instance. Tokens are managed in the web client only: the API does not create a token from another token.

Many endpoints work inside one workspace: nodes and their samples, data, connections, submissions and tasks. Name it in the X-Workspace header, with its identifier:

X-Workspace: 143fbb1c-a639-4c33-8c41-2c1c02d7b8c2

The reference lists the header among the parameters of each endpoint that needs it. GET /api/workspaces lists the workspaces of the account, with their identifiers.

Every instance serves an interactive reference of its API, for the version it runs, and its OpenAPI schema:

WhatPath on the API of the instance
Interactive reference (Swagger UI), where you can try the endpoints/api/schema/swagger-ui/
OpenAPI schema, to generate a client or import it into a tool/api/schema/

For example, on the national instance run by the French Institute of Bioinformatics: api.madbot.france-bioinformatique.fr/api/schema/swagger-ui/. On a local instance: http://localhost:8000/api/schema/swagger-ui/.

To call an endpoint from Swagger UI:

  1. Create a personal access token (see above), and copy it with Copy token (with Bearer).
  2. Select Authorize. In the ApiKeyAuth box, paste the token in Value, as Bearer pat_…, then select Authorize and Close.
  3. Open an endpoint, select Try it out, fill in its parameters, X-Workspace among them when it needs one, then select Execute.

An endpoint that lists resources returns them page by page:

Query parameterMeaning
pThe page, from 1.
page_sizeThe number of results per page: 10 by default, 500 at most.

The response gives the results of the page and where to go next (here with the results shortened):

{
"count": 2,
"next": "http://localhost:8000/api/workspaces?p=2&page_size=1",
"previous": null,
"results": [{ "id": "143fbb1c-a639-4c33-8c41-2c1c02d7b8c2", "name": "Coastal erosion survey" }],
"current_page": 1,
"total_pages": 2
}

To read the whole list, follow next until it is null. Many lists also take search and ordering: the reference gives the parameters of each one.

An error comes with an HTTP status and a body of the same shape:

{
"code": "header_validation_error",
"message": "Invalid header. Check the `details` property for more details.",
"details": [{ "parameter": "x-workspace", "code": "required", "message": "This field is required." }]
}
  • code names the kind of error, for a script to test.
  • message describes it for a person.
  • details lists the causes: the parameter at fault when there is one, a code and a message.
StatuscodeWhen
400body_validation_error, query_validation_error, header_validation_errorThe body, a query parameter or a header is missing or invalid.
401unauthorizedThe token is missing, invalid, expired or revoked.
403forbiddenThe token lacks the scope, the account is not approved, or it is not a member of the resource.
404object_not_foundThe resource does not exist.
500internal_server_errorAn unexpected error. details gives an identifier: send it to the administrators of the instance.

This script creates a workspace and two nodes in it, reads them back one page at a time, and shows an error. It runs on a local instance (see Set up a development environment), with curl and jq.

Create a token with the read and write scopes in your local web client, then set the address of the API and the token:

Terminal window
export MADBOT_API=http://localhost:8000
export MADBOT_TOKEN=pat_…

Check that the API answers. This endpoint needs no token:

Terminal window
curl -s "$MADBOT_API/api/version"
{"version":"2.1.0","plugins_api_version":"2.0.1"}

Create a workspace, and keep its identifier:

Terminal window
WORKSPACE=$(curl -s -X POST "$MADBOT_API/api/workspaces" \
-H "Authorization: Bearer $MADBOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Coastal erosion survey"}' | jq -r .id)
echo "$WORKSPACE"

Create two nodes in it:

Terminal window
for title in "Spring campaign" "Autumn campaign"; do
curl -s -X POST "$MADBOT_API/api/nodes" \
-H "Authorization: Bearer $MADBOT_TOKEN" \
-H "X-Workspace: $WORKSPACE" \
-H "Content-Type: application/json" \
-d "{\"title\": \"$title\"}" | jq -r '.id + " " + .title'
done

Read them back, one per page, from the first page until next is null:

Terminal window
page="$MADBOT_API/api/nodes?page_size=1"
while [ "$page" != "null" ]; do
response=$(curl -s "$page" \
-H "Authorization: Bearer $MADBOT_TOKEN" \
-H "X-Workspace: $WORKSPACE")
echo "$response" | jq -r '"page \(.current_page)/\(.total_pages): \(.results[0].title)"'
page=$(echo "$response" | jq -r .next)
done
page 1/2: Spring campaign
page 2/2: Autumn campaign

Without the X-Workspace header, the API answers with an error:

Terminal window
curl -s "$MADBOT_API/api/nodes" -H "Authorization: Bearer $MADBOT_TOKEN" | jq
{
"code": "header_validation_error",
"message": "Invalid header. Check the `details` property for more details.",
"details": [
{
"parameter": "x-workspace",
"code": "required",
"message": "This field is required."
}
]
}

The workspace and its nodes are in your local web client. Delete the workspace from there, or with DELETE /api/workspaces/{id}.