Skip to content
Building X

Explore our APIs. Develop innovative applications and integrations or extend the functionality of existing applications.

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 base 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

ParameterValue
client_id(mandatory) The client_id you received when registering
client_secret(mandatory) The client_secret you received when registering
audience(mandatory) https://horizon.siemens.com
grant_type(mandatory) client_credentials

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

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

KeyDescription
selfthe current page of data
firstthe first page of data
lastthe last page of data
prevthe previous page of data
nextthe next page of data

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.

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

TermDescription
idA unique identifier for this particular occurrence of the problem.
statusThe HTTP status code applicable to this problem, expressed as a string value.
codeAn application-specific error code, expressed as a string value.
titleA short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

Example Response

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

HTTP Status Codes

TermDescription
200Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
201The request has been fulfilled, resulting in the creation of a new resource.
202The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.
204The server successfully processed the request and is not returning any content.
400The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
401Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.
403The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort. This code is also typically used if the request provided authentication via the WWW-Authenticate header field, but the server did not accept that authentication.
404The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
405A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource.
406The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
409Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
429The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.
500A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
503The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.
504The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.

Standards & Formats

TermDescription
RFC 3339 Date and Time on the Internet: TimestampsThe chosen way to represent time and dates.
The OAuth 2.0 Authorization FrameworkOAuth 2.0 for authorization and client_credentials grant type.
WGS84The representation of geographical coordinates.
Project HaystackProject Haystack is an open source initiative to streamline working with data from the Internet of Things in the domain of Building Automation.
RFC7946 The GeoJSON FormatGeoJSON is a geospatial data interchange format based on JavaScript Object Notation (JSON).
JSON:APIJSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.

JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

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 code.

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 long 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 we will inform all registered users at least 3 months in advance of API sunset.