This is the ThingsDB documentation for version v0, click here for the latest version!

HTTP API

Before using the HTTP API, make sure at least one node has the API port enabled. By default the API port is enabled and listening to TCP port 9210, but can be disabled or changed with the http_api_port in the configuration file or with the THINGSDB_HTTP_API_PORT environment variable.

The API has support for both MessagePack and JSON and can be used to perform queries and run procedures.

Use MessagePack if possible since this is the data serialization protocol which is used by ThingsDB internally and will therefore be a faster than JSON. It also allows for sending and receiving binary data and is usually more compact than JSON. In most examples we use JSON just because it is more readable.

Headers

The header field Content-Type is required and needs to be either application/msgpack or application/json.

Query request

field description
type Required and must be query for a query request.
code Required string with the query code to preform.
vars Optional and may contain a map where the keys are variable names and the values will be the variable values.

Query example

Example using curl with token authentication: (using a playground collection Doc)

curl --location --request POST 'https://playground.thingsdb.net//Doc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Fai6NmH7QYxA6WLYPdtgcy' \
--data-raw '{
	"type": "query",
	"code": ".greetings.choice();"
}'

choice() returns a random item from the .greetings array)

Possible response

"Hi!"

Besides the preferred token authentication, the HTTP API has also support for basic authentication.

Another curl example using basic authentication using user Doc with password pass:

curl --location --request POST 'https://playground.thingsdb.net//Doc' \
--header 'Content-Type: application/json' \
--user Doc:pass \
--data-raw '{
	"type": "query",
	"code": "1 + 1;"
}'

Example response:

2

Run request

field description
type Required and must be run for a run request.
name Name of the procedure to run.
args Array or map with arguments for the procedure.

Run example

The ThingsDB playground has a collection Doc with a procedure named multiply which accepts two arguments and returns the two arguments multiplied.

If you want to create the multiply procedure yourself, this is the code:

new_procedure('multiply', |a, b| a*b);

Example using the playground:

curl --location --request POST 'https://playground.thingsdb.net//Doc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Fai6NmH7QYxA6WLYPdtgcy' \
--data-raw '{
	"type": "run",
	"name": "multiply",
	"args": [6, 7]
}'

Response

42

Instead of providing the arguments as an array, they also could be given as a map, for example {"a": 6, "b": 7}.