B_ig B_uilding Data

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 1^rst, 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."
}