Boomack Logo
light_mode
dark_mode

API Reference

The Boomack Server offers all its capabilities via an HTTP API, loosely following the RESTful style.

The preferred way of interacting with a Boomack Server from you own program, is to use one of the clients. If there is no client for your programming language, or you only want to issue a small number of specific requests, you can use a generic HTTP client in your language, and interact with the server directly.

The complete API is documented with the OpenAPI Specification 3, and visualized in a Swagger viewer:

https://api.boomack.com

You can even try out examples directly from the documentation, if you start a local Boomack Server.

Hint: If you want to know what kind of HTTP request(s) the Boomack Client CLI boom is running in the background, try out the switches --dry and --curl.

Authentication ↑

By default the Boomack API is not protected by authentication. However, the default configuration is intended for local use only. As soon as the API is reachable by someone else than the person running the Boomack Server, it is highly advised to activate and configure the authentication of the server.

See API Authentication in the server configuration page for more details.

As soon as the authentication of the server is activated, an API client needs to provide an access token with every API request. The access token is expected in the HTTP header field Authorization with the prefix Token␣.

Authentication Example ↑

If an access token edc3eacdb404143ad12a1eb2e667 is configured, the access token must be send in the HTTP header of every API request:

Authorization: Token edc3eacdb404143ad12a1eb2e667

To learn how to authenticate with the Boomack Client CLI, takte look at the configuration section of the Boomack Client CLI.

Basically you have the following options:

A config file for the Boomack CLI can look like this:

YAML
JSON
server:
  url: http://127.0.0.1:3000
client:
  token: edc3eacdb404143ad12a1eb2e667

{
  "server": { "url": "http://127.0.0.1:3000" },
  "client": { "token": "edc3eacdb404143ad12a1eb2e667" }
}

Response Types ↑

Currently Boomack supports the following MIME types in its responses. Meaning, you can use the following MIME types in the Accept header field of your API requests.

Panel Management ↑

The panels and slots are managed by the following API routes.

For a more detailed explanation please consult the OpenAPI specification.

Panel Layout Structure ↑

The data structure of a panel layout consists of the following properties:

Grid Layout Properties

Panel layouts with the type set to "grid", can have the following additional properties:

Document Layout Properties

Panel layouts with the type set to "document", can have the following additional properties:

Slot Properties

A slot in a panel layout is defined with the following properties:

Slot properties, only supported in a grid layout:

Slot properties, only supported in a document layout:

Display Request ↑

A display request delivers hyper media content to the Boomack Server with the intention of displaying it on a panel inside a slot.

A display request is formatted with JSON or YAML and send to the following route:

One call to the route can contain one single display request as a map or multiple display requests in an array.

A display request has the following structure:

Important: YAML encoded display requests are only supported, if configuration option api.request.yaml is set to true. If the option is set to false only JSON formatted requests are allowed.

The content can be transmitted in one of the three properties text, data, or src:

Stream Display Request ↑

Stream display requests are HTTP requests to the routes:

The media content is transferred as the body of the HTTP request. The target panel and slot are encoded as part of the URL. The other parts of a display request are encoded in HTTP header fields:

Attention: Some reverse-proxy servers, like NGiNX, for example, limit the size of the whole HTTP header including the request line to 4KB. If the display options in a stream request are too large, presets should be used.

See Stream Display Request on the concepts page for more details.

Evaluation Request ↑

An evaluation is triggered by the following routes:

The first route supports JSON or YAML as content type for the body. It expects either a map with the properties panel and script. Or an array of such maps. The panel property must be set to an ID of an existing panel. If the panel property is omitted, the panel ID default is used as default. The script property must be set to a string, containing valid JavaScript code.

The second route expects the content type application/javascript and therefore, the JavaScript code directly as body. Other than the first route, the second can only trigger the evaluation of one script text in one target panel. The ID of the target panel is given as part of the path in the URL.

See Evaluation Request on the concepts page for more details.

Preset Management ↑

Presets are managed with the following routes:

The PUT route supports JSON and YAML as content type for the body. It expects a single map with display options.

See Preset on the concepts page for more details.

Media Type Management ↑

Media types are managed with the following routes:

The PUT route supports JSON and YAML as content type for the body. It expects a single map with the following properties:

See Media Type on the concepts page for more details.

Action Management ↑

Actions are managed with the following routes:

The PUT route supports JSON and YAML as content type for the body. It expects a single map with the definition for an action. The only required property is the type property with the ID of an action type. Additionally supported properties depend on the selected action type.

JSON
YAML
{
  "type": "the action type",
  ...
}

type: the action type
...

See Action on the concepts page for more details.

Export ↑

Export requests trigger an export of all panels, an individual panel, or an individual slot to the filesystem of the Boomack Server. The following routes allow to trigger the export:

The routes expect a JSON or YAML body with a single map, holding the following properties:

Important: The export to the local filesystem of the Boomack Server is deactivated by default. Not only are the API routes deactivated and need to be activated with the configuration option api.enable.export= true, but the export is still deactivated, as long as no base path is set for the export. The base path is set with the configuration option export.local.location.

See Export on the concepts page for more details.