Developer's Guide¶

The Siemens Building X APIs are based on the JSON:API specification. On top of JSON:API we have applied some conventions of our own. This document aims to describe those and give you other useful information to get started and operate an application based on our APIs.

Authentication¶

You can use your Machine User credentials to obtain an API Token using the OAuth 2.0 Client Credentials grant.

The token endpoint is found at: https://siemens-bt-015.eu.auth0.com/oauth/token

For information on how to create you own client credentials, or Machine User, check out the Getting Started. Refer to Create a Token for more hands-on guidance.

Token Validity¶

The token has limited validity. After expiry you may create a new token by repeating the create token flow. The JWT itself, as well as the response of the create token request, will provide information about the expiry time. In the JWT there is a exp claim, and in the response, there is a expires_in property.

Filtering¶

Filters are provided as query string parameters using the filter family style. The available filters for each list operation are described in the API Reference.

Example¶

Filter devices with serialNumber of value 12345.

GET /partitions/5435b9ac-8823-9e89-804bd4710e90/devices?filter[serialNumber]=12345

Pagination¶

Paging functionality is provided as query string parameters using the page family style. The available paging strategy and specific options for each list operation are described in the API Reference.

Controlling Page Size¶

Page size is controlled by using the page[limit] param.

Example¶

Set the maximal number of records to receive in the response to 5.

GET /partitions/5435b9ac-8823-9e89-804bd4710e90/devices?page[limit]=5

Navigating Pages¶

Navigation links are provided within the links property using different keys to represent different targets as described in the table below.

Keys are omitted to indicate that a particular link is unavailable.

When listing resources, e.g. devices, there are typically one or two links present. self is always present and next is present if there is a next page to fetch. When the next link is no longer in the response, then there are no more pages to fetch.

Inclusion of related resources¶

Building X APIs adhere to the JSON:API specification. For some operations the include parameter is supported. If the include parameter is specified for an operation it can be used with the defined values. This gives you the option to include resources that appear in the relationships without performing another request to the server.

When used, the response will contain a top-level property included which contains the requested resources.

In addition, there is a parameter called field, available for some operations. By specifying it, the client can retrieve certain fields that are not otherwise in the response.

Request ID¶

Every response contains a response header called X-Request-Id. The value of the header is a unique identifier of the transaction. Use this and share with the Development Team when reporting problems.

Example Response¶

HTTP/1.1 400 Bad Request
X-Request-Id: 2e92b826-8d7f-4a86-bf84-241c02c1b90a

JSON Error Object¶

Example Response¶

{
    "errors":[
        {
            "id": "2e92b826-8d7f-4a86-bf84-241c02c1b90a",
            "status": "400",
            "code": "34-0001",
            "title": "Missing mandatory property 'name'"
        }
    ]
}

HTTP Status Codes¶

Standards & Formats¶

Policies¶

Rate Limitation¶

Each client may make 10 API request per second. If you have additional requirements please contact us.

Exceeding the rate limit will result in a 429 error.

Compatibility Policy¶

The APIs will evolve over time by the introduction of new properties and endpoints. Prepare your parsers for new properties, so that they are allowed in order not to break the client.

Backwards Compatibility¶

As much as possible, we strive not to change the behavior of existing properties. However, the behavior of an API may change without warning if the existing behavior is incorrect or constitutes a security vulnerability.

Deprecation¶

We reserve the right to deprecate APIs in full or in part. Usually this is only done after introducing improved ways to achieve the same goals.

When deprecating an API, we will notify all registered users at least 3 months in advance.