HTTP

The main Blockbax API is a HTTP API which provides programmatic access to all the platforms operations. A major use case of the API is sending measurements. Batches of up to 500 measurements can be sent via our HTTP API. To map measurements to subjects and metrics you can specify your own IDs. We call these ingestion IDs, by default these are derived from the subjects’ external IDs and metrics’ external IDs (e.g. subjectExternalId$metricExternalId) but you can also override these with custom ones. More information can be found in the relevant section of the API documentation. If you are unable to work with the default API payload format you can write your own custom JavaScript payload conversion function using inbound connectors.

Another important use case is to build custom user-facing applications on top of our platform or synchronizing reference data (such as data from asset management, ERPs, GISs, PLM software, etc.).

Inbound connectors

Inbound connectors are integrations to ingest measurements into the Blockbax Platform. In the case of HTTP, there is a default connector that can be reached by posting to this end-point:

https://api.blockbax.com/v1/projects/<PROJECT_ID>/measurements

This end-point expects measurements in the format described in our API reference documentation.

If the payload format is different from the default format, you can use a custom inbound connector. A custom inbound connector has a payload conversion script that is defined as a plain JavaScript function. A dedicated page about payload conversion describes how to develop such a function. This also allows you to log certain things about your payload. A custom inbound connector can be reached at the following end-point:

https://api.blockbax.com/v1/projects/<PROJECT_ID>/measurements?inboundConnectorId=<INBOUND_CONNECTOR_ID>

Note that we do not process payloads with a size over 200 KiB. When this happens an error log will be output.

Settings

Auto-create subjects

Measurements are mapped to subjects and metrics by so-called ingestion IDs. By default, an ingestion ID is derived from the subjects’ external ID and the metrics’ external ID (e.g. MyCar$Location). You can also override this default with a custom ingestion ID. If a measurement with an unknown ingestion ID is encountered, Blockbax tries to find a single metric with an external ID equal to the part after the dollar sign. If this is successful, a subject will be created with an external ID equal to the part before the dollar sign. For example, for the ingestion ID MyCar$Location a subject with external ID MyCar will be created if the metric with external ID Location can be linked to exactly one subject type.

Integration templates

Inbound connectors can also be configured from a integration template. To make integrating with Blockbax as easy as possible we provide integration templates that can integrate any available third party platform or device with a few clicks. We use integration templates in most of our connection guides.

API

Apart from ingesting measurements, the HTTP API can also be used to access core functionality of the Blockbax platform. This part of the API is described in a a different section and requires knowledge of HTTP API concepts. In the case of our API this means the URLs are resource-oriented and HTTP status codes are used to indicate success or failure. Data returned from our API will be in JSON format for all requests. More info can be found in the separate API documentation.