Get started with API

Everything you can do with data in the Databucket web application, you can also do through the REST API: insert, search, modify, reserve and delete data. This page shows how to sign in and how to call the data endpoints. In the examples, <databucket url> is the address of your Databucket server, e.g. http://localhost:8080.

API documentation (Swagger)

The full API specification is served by your Databucket server:

Swagger UI: <databucket url>/swagger-ui/index.html
OpenAPI specification (JSON): <databucket url>/v3/api-docs

To try the data API in the Swagger UI: sign in with POST /api/public/signin ("Try it out"), copy the token from the response, click Authorize, paste the token and confirm. The next "Try it out" requests send it. The Swagger UI lists only the public API: signing in and the bucket data operations.

Before you start

To use the data API you need a Databucket user who:

signs in with a user name and password. Single sign-on accounts are meant for the web application. For tests and other automation, create a dedicated user, e.g. with the ROBOT role,
has the MEMBER or ROBOT role (see Roles & permissions),
is assigned to the project and has access to the bucket.

Sign in

Send the user name and password to POST <databucket url>/api/public/signin. Add projectId when the user is assigned to more than one project:

{
  "username": "robot",
  "password": "secret",
  "projectId": 1
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "username": "robot",
  "project": {
    "id": 1,
    "name": "Demo",
    "description": null,
    "enabled": true,
    "expired": false
  },
  "roles": ["ROBOT"]
}

When the user is assigned to one project, you can omit projectId; the user is signed in to that project.
When the user is assigned to several projects and projectId is omitted, the response contains no token, only the list of the user's projects. Sign in again with one of their ids.
Wrong user name or password, or a disabled user: 401. Expired user, disabled or expired project, or a project the user is not assigned to: 403. The reason is in the message field.
When the user has to change the password, the response contains "changePassword": true instead of a project. Sign in to the web application once and change the password.

Call the API

Send the token in the Authorization header of every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

The token is valid for the number of hours set in jwt.expire.hours (24 in the example configuration, see Installation). There is no refresh token: when the token expires, the API answers 401 and you sign in again. The token is bound to the project you signed in to; to work with another project, sign in with its projectId.

Data endpoints

All data endpoints start with <databucket url>/api/bucket/{bucketName}, where {bucketName} is the bucket name.

Method	Path	Body	What it does
POST	`/api/bucket/{bucketName}`	data	Inserts one data row
POST	`/api/bucket/{bucketName}/multi`	array of data	Inserts several data rows, in one transaction: all of them or none
GET	`/api/bucket/{bucketName}/{ids}`		Gets data by ids, e.g. `/12` or `/12,13,14`
POST	`/api/bucket/{bucketName}/get`	`rules`, `columns`	Gets data matching the rules
PUT	`/api/bucket/{bucketName}/{ids}`	changes	Modifies data by ids
PUT	`/api/bucket/{bucketName}`	changes and `rules`	Modifies data matching the rules
POST	`/api/bucket/{bucketName}/reserve`	`rules`	Reserves data matching the rules
DELETE	`/api/bucket/{bucketName}/{ids}`		Deletes data by ids
DELETE	`/api/bucket/{bucketName}`	`rules`	Deletes data matching the rules

The data body has these optional items: tagId, reserved and properties (any JSON object). When modifying data, properties replaces all the properties, and reserved: true changes only the rows that are not reserved yet (a row reserved by someone has to be released first). To change only some of them, use propertiesToSet (an object of JSON paths and values, e.g. {"$.address.city": "Paris"}) and propertiesToRemove (a list of JSON paths, e.g. ["$.phone"]) instead.

Modifying and deleting by rules require at least one rule, so that you don't change the whole bucket by accident.

/get and /reserve accept these query parameters:

limit - how many data rows to return or reserve, 1 by default. For /get, limit=0 returns only the number of matching rows (total).
page - (/get only) the page number, 1 by default.
sort - the order, id by default. Use a field or property name, optionally wrapped in asc() or desc(), e.g. sort=desc(modifiedAt) or sort=$.lastName. Properties are sorted by their value (numbers as numbers). Use sort=random for a random order.

How to write rules is described on the Rules page, and columns on the Custom columns page.

The reserve response says how many rows were reserved (reserved), how many unreserved rows still match the rules (available), and contains the reserved rows (data). A user with the ADMIN role can reserve data for another user with targetOwnerUsername in the body.

In a bucket with protected data, users without the ADMIN role can see and change only the data they reserved.

Example with curl

Sign in and keep the token:

TOKEN=$(curl -s -X POST <databucket url>/api/public/signin \
  -H "Content-Type: application/json" \
  -d '{"username": "robot", "password": "secret", "projectId": 1}' | jq -r .token)

Insert a data row:

curl -X POST <databucket url>/api/bucket/users \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"properties": {"firstName": "John", "lastName": "Lennon", "active": true}}'

Get up to 10 active users, the newest first:

curl -X POST "<databucket url>/api/bucket/users/get?limit=10&sort=desc(id)" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"rules": [["$.active", "==", true]]}'

Reserve one unreserved active user:

curl -X POST "<databucket url>/api/bucket/users/reserve?limit=1" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"rules": [["reserved", "==", false], ["$.active", "==", true]]}'

Delete the data row with id 12:

curl -X DELETE <databucket url>/api/bucket/users/12 -H "Authorization: Bearer $TOKEN"

Errors

Errors are returned with a message field describing the problem, e.g. {"message": "The tag 999 doesn't exist"} or, for an invalid field, {"message": "icon.svg: The icon contains a forbidden element: style"}. Server errors (500) name the request id, which is also in the X-Request-Id header, to find the details in the server log.

Status	Meaning
400	The request is invalid, e.g. both sides of a rule are constants, a value that doesn't fit the type used in a rule, an invalid field
409	The data conflicts with other data
401	Missing, invalid or expired token; wrong user name or password
403	The user may not sign in to the project, or doesn't have the role required by the endpoint
404	The bucket doesn't exist or the user has no access to it
406	The request can't be done, e.g. an unknown tag, modifying or deleting without rules, a limit lower than 1 when reserving

Next steps

Rules, Operators, Fields, Functions and Rule examples - how to select data
Custom columns - how to get only some fields and properties
Example Java project - a client written in Java

Wiki

Work in the project

Project settings

Management

API

Get started with API