Bosch IoT Rollouts

Management API

The Management API is a RESTful API that enables to perform Create/Read/Update/Delete operations for provisioning targets (i.e. devices) and repository content (i.e. software). Based on the Management API you can manage and monitor software update operations via HTTP/HTTPS. The Management API supports JSON payload with Hypermedia as well as filtering, sorting and paging. Furthermore the Management API provides permission based access control and standard roles as well as custom role creation.

The API is protected and needs authentication and authorization based on the security concept. Note that the tenant information has to be provided differently, either within the username or as a path parameter inside the URL, depending on the authentication concept that is used. For more details please refer to section Authentication and authorization.


Access the Management API reference documentation at https://docs.bosch-iot-suite.com/rollouts/rest-api/mgmt.html.


Table of contents:

API version

Bosch IoT Rollouts provides a consistent Management API interface that guarantees backwards compatibility for future releases by version control.

The current version of the Management API is version 1 (v1). Use the following URLs to access the Management API depending on your preferred way of authentication:

  • https://api.eu1.bosch-iot-rollouts.com/rest/v1/ when authenticating with a specific Bosch IoT Rollouts's tenant system username and password, or

  • https://api.eu1.bosch-iot-rollouts.com/<TENANT_ID>/rest/v1/ , when authenticating via OAuth2 tokens i.e. logging in as a Bosch employee or via SingleKeyId.

Eclipse hawkBit™ compatibility

Bosch IoT Rollouts Management API is fully compatible to Eclipse hawkBit’s Management API in version 1 (v1).

The hawkBit project provides Java representations that allow to decode the message body at runtime into a Java object. The Java models can also be used to encode Java objects into JSON bodies to send a requests to Bosch IoT Rollouts. The project provides as well examples leveraging the Feign client.

The model is available on maven central, e.g. in Maven:

<dependency>
<groupId>org.eclipse.hawkbit</groupId>
<artifactId>hawkbit-mgmt-api</artifactId>
<version>0.2.0</version>
</dependency>

API resources

Supported HTTP-methods are:

  • GET

  • POST

  • PUT

  • DELETE

Available Management APIs resources are:

Please be aware of the Quota.

Query parameter

For filtering, sorting and paging as well as using the Feed Item Query Language (FIQL) see Query parameters.

Headers

For all requests an Authorization header has to be set, depending on the authorization concept that is used.

Option 1: Basic Auth

  • Username: tenant\username

  • Password: password

Option 2: OAuth2 access token

Note: The tenant information has to be set as a path parameter inside the URL,
e.g. https://api.eu1.bosch-iot-rollouts.com/<TENANT_ID>/rest/v1/.
The access token has to be provided as a Bearer token inside the header:

  • Authorization: Bearer <ACCESS_TOKEN>

Also have a look at section Authentication and authorization.

In addition, for POST and PUT requests the Content-Type header has to be set. Accepted content-types are:

  • application/json

  • application/hal+json

Request Body

Besides the relevant data (name, description, createdBy etc.) of a resource entity, a resource entity also has URIs (_links) to linked resources entities.

A distribution set entity may have for example URIs to artifacts, software modules, software module types and metadata.

"_links": {
"artifacts": {
"href": "https://api.eu1.bosch-iot-rollouts.com/rest/v1/softwaremodules/83/artifacts"
},
"self": {
"href": "https://api.eu1.bosch-iot-rollouts.com/rest/v1/softwaremodules/83"
},
"type": {
"href": "https://api.eu1.bosch-iot-rollouts.com/rest/v1/softwaremoduletypes/43"
},
"metadata": {
"href": "https://api.eu1.bosch-iot-rollouts.com/rest/v1/softwaremodules/83/metadata?offset=0&limit=50"
}
}


With the tenant as the path parameter respectively:

"_links": {
"artifacts": {
"href": "https://api.eu1.bosch-iot-rollouts.com/SPDEMO/rest/v1/softwaremodules/83/artifacts"
},
"self": {
"href": "https://api.eu1.bosch-iot-rollouts.com/SPDEMO/rest/v1/softwaremodules/83"
},
"type": {
"href": "https://api.eu1.bosch-iot-rollouts.com/SPDEMO/rest/v1/softwaremoduletypes/43"
},
"metadata": {
"href": "https://api.eu1.bosch-iot-rollouts.com/SPDEMO/rest/v1/softwaremodules/83/metadata?offset=0&limit=50"
}
}