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.
Authenticate with a personal access token
Section titled “Authenticate with a personal access token”A script authenticates with a personal access token, created in the web client:
- Open the user menu, then Account settings, then Tokens.
- Select Create a new token, name it and choose its scopes:
read: read the resources;write: create, change and delete them;*: full access, alone.
- 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.
Name the workspace
Section titled “Name the workspace”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-2c1c02d7b8c2The 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.
Try the endpoints in Swagger UI
Section titled “Try the endpoints in Swagger UI”Every instance serves an interactive reference of its API, for the version it runs, and its OpenAPI schema:
| What | Path 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:
- Create a personal access token (see above), and copy it with Copy token (with Bearer).
- Select Authorize. In the
ApiKeyAuthbox, paste the token in Value, asBearer pat_…, then select Authorize and Close. - Open an endpoint, select Try it out, fill in its parameters,
X-Workspaceamong them when it needs one, then select Execute.
Read a list, page by page
Section titled “Read a list, page by page”An endpoint that lists resources returns them page by page:
| Query parameter | Meaning |
|---|---|
p | The page, from 1. |
page_size | The 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.
Read an error
Section titled “Read an error”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." }]}codenames the kind of error, for a script to test.messagedescribes it for a person.detailslists the causes: the parameter at fault when there is one, a code and a message.
| Status | code | When |
|---|---|---|
| 400 | body_validation_error, query_validation_error, header_validation_error | The body, a query parameter or a header is missing or invalid. |
| 401 | unauthorized | The token is missing, invalid, expired or revoked. |
| 403 | forbidden | The token lacks the scope, the account is not approved, or it is not a member of the resource. |
| 404 | object_not_found | The resource does not exist. |
| 500 | internal_server_error | An unexpected error. details gives an identifier: send it to the administrators of the instance. |
A first script
Section titled “A first script”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:
export MADBOT_API=http://localhost:8000export MADBOT_TOKEN=pat_…Check that the API answers. This endpoint needs no token:
curl -s "$MADBOT_API/api/version"{"version":"2.1.0","plugins_api_version":"2.0.1"}Create a workspace, and keep its identifier:
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:
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'doneRead them back, one per page, from the first page until next is null:
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)donepage 1/2: Spring campaignpage 2/2: Autumn campaignWithout the X-Workspace header, the API answers with an error:
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}.

