Bosch IoT Things HTTP API

Details regarding the syntax can be found in following sections and at the REST-like HTTP API description application itself.

The interactive API documentation supports you to instantly try it out.
In order to try it out please start by booking a free plan - see Book the Bosch IoT Things cloud service.
Please request a service plan as you will definitely need an identifier for each single API call.

The Bosch IoT Things HTTP API uses response status codes (see RFC 7231) to indicate whether a specific request has been successfully completed, or not. However, the descriptions we provide additionally to the status code (e.g. in our API docs, or error codes like. “solutions:transaction.count.exceeded”) might change without advance notice. These are not be considered as official API, and must therefore not be applied in your applications or tests.

Navigate to https://apidocs.bosch-iot-suite.com and select Bosch IoT Things - API v2 at the upper right drop-down-menu.

Authorize

The entry point is https://apidocs.bosch-iot-suite.com

1. Select a spec: Bosch IoT Things - API v2
2. Servers:
   This field shows the service endpoint, which differs depending on which environment you subscribed for:
   • e.g. https://things.eu-1.bosch-iot-suite.com/api/2 for Amazon Web Services infrastructure
     Find the list of all endpoints at our FAQ section How to find the endpoints for my subscription?
3. Authorize: opens a pop-up-dialog with the option to specify bearerAuth (http, Bearer). This expects a JWT issued by a supported identity provider, e.g. Suite Auth.

Headers

While using the Bosch IoT Things HTTP API programmatically you will need:

1. The header for authenticating your solution as described at Authenticate as a technical client:
   x-cr-api-token=<$your-apiToken>
2. The header for authenticating the current user as described at Authenticate as a user:
   • with a JSON Web Token (JWT)
     Authorization=Bearer <$ your token>
3. The header for specifying the content type, e.g.
   Content-Type=application/json

Channel

The Bosch IoT Things HTTP API supports two types of channel for communication.

• The default value of the channel parameter is twin, to communicate with the digital twin.
• The channel parameter can be changed to live, to communicate with the real device.

The channel parameter can be specified via HTTP header or via HTTP query parameter.

For more information about the channel concept see Ditto HTTP API overview

Migration from API 1 to API 2

In case you need to migrate a thing which was created via API 1 to API 2, please note that you need to migrate the access control list entries (ACL) into a policy, and to assign your thing to such a policy.

1. Request the thing to be migrated, via API 2 and use the field-selector to specify that the inline policy (i.e. _policy) should also be retrieved.

   GET https://things.eu-1.bosch-iot-suite.com/api/2/things/{$thingId}?fields=_policy

   Retrieve a specific Thing

2. Create a new policy from the content of the requested inline policy, with a policyId of your choice (e.g. same as the thingId).

   PUT https://things.eu-1.bosch-iot-suite.com/api/2/policies/{$policyId}

   Create or update a Policy with a specified ID

3. Assign the new policyId to the thing to be migrated.

   PUT https://things.eu-1.bosch-iot-suite.com/api/2/things/{$thingId}/policyId

   Create or update the Policy ID of a Thing

Note: Henceforth the thing cannot be read nor written via API 1.
Please make sure all other parts of your application (e.g. device integration, business UI) are using API 2 as well.