Big Building Data

Documentation
A house for all your sensor & data.
Redundant, fast & secured data storage.
A single REST API covering all your needs.

Full documentation

Available are the Swagger UI and the OpenAPI 3.0 YAML file. The latter can be imported in many tools such as PostMan.

Additional information

Authentication

Getting an apikey

To access most of the endpoints, you need an APIKEY. Apikeys can be read-only or read-and-write. To create an apikey, you need first to login using your username/password. This will create a read-and-write apikey limited in time. Using the former, you can access the Apikeys endpoint to generate new apikeys.

Using an apikey

Once you have an apikey, you need to include it in queries using one of the following methods.

Headers include the two headers bbuser: your-user-id and bbtoken: your-apikey-secret. Example:

curl -H "bbuser: 1" -H "bbtoken: 007237385b79dbb11917b472986d9a60" <url>

Basic authentication this uses the common Authorization header, where userid:secret is transmitted as a base64 string. Example:

curl --user "1:007237385b79dbb11917b472986d9a60" <url>

As a rule of thumb, any non-GET endpoint will require a read-and-write apikey.

Date format

The API manipulates many dates. For output, the format follows the ISO UTC format, with milliseconds:
YYYY-MM-ddTHH:mm:ss.SSSZ
For input, the API is quite lenient and will accept any truncation, as well as timezone information (no timezone means UTC !). In general, the only constraint is that the date is after January 1rst, 2016. To make it clearer, here are some examples:
Input Interpretation
2020-03-21T08:14:00.123 2020-03-21T08:14:00.123Z
2020-03-21T10:00+02:00 2020-03-21T08:00:00.000Z
2020-3-1T1:00 2020-03-01T01:00:00.000Z
2020-03-21T08 2020-03-21T08:00:00.000Z
2020-03-21 2020-03-21T00:00:00.000Z
2020-03 2020-03-01T00:00:00.000Z
2020 2020-01-01T00:00:00.000Z
20 0020-01-01T00:00:00.000Z Invalid !

Common responses

The API uses consistent HTTP status codes throughout the various endpoints. Below are the most common:
Code Meaning Description
200 Success Everything worked as expected
304 Not Modified Not an error per se, but the call didn't modify any resource. This will happen for example if you ask to delete a non-existant resource.
400 Bad Request Some provided information (query parameters, body, etc.) is invalid: wrong format, missing property, etc.
401 Unauthorized The resource is protected and the requests lacks credential information.
403 Forbidden The resource is protected the provided credentials are invalid. This can be because of wrong credentials or because the apikey/user is not allowed to manage this resource.
500 Internal Server Error We made a mistake. Sincere apologies.
For any status code above 3XX, you can expect a body of the following structure:
{ "exception": "string", "details": object }
The exception field is a single camelcase identifier for the exception, while details is populated differently depending on the status code. For 400 - Bad Request, a JSON object that lists all wrong parameters. The structure is thus "property": "detailed message". Example:
{
  "exception" : "WrongParamsException",
  "details" : {
    "owner" : "must not be null",
    "name" : "size must be between 3 and 45"
  }
}
For status codes ≠ 400, the details is a string with either a clear message or an abstract of the exception's associated message. Examples:
{
  "exception" : "HttpMediaTypeNotSupportedException",
  "details" : "Content type 'application/x-www-form-urlencoded;charset=UTF-8' not supported"
}
{
  "exception" : "ItemNotFoundException",
  "details" : "The object group (101) was not found or can't be accessed with this apikey."
}