Updates at the HTTP API

Custom OpenID Connect client support - NEW

The Solutions resource now offers additionally clients sub-resources, e.g.

GET - PUT - DELETE   /solutions/{solutionId}/clients
GET - PUT - DELETE   /solutions/{solutionId}/clients/{clientId}

Integration of project specific custom OAuth2 authorization servers (based on OpenID Connect Discovery 1.0) can be supported upon request. Feel free to contact us via https://www.bosch-iot-suite.com/support/ .

To add such a subject to a policy of a specific thing see Policies > custom_subject_of_your_openid_connect_authentication_provider


Removed deprecated prefixed for policies

Following prefixes which have been announced deprecated since January 2018 will not be supported with our service update in September 2019:

  • https://permissions.apps.bosch-iot-cloud.com/authentication - formerly allowed for a JSON Web Token issued by Bosch IoT Permission (authentication token)
  • https://permissions.apps.bosch-iot-cloud.com/authorization - formerly allowed for a JSON Web Token issued by Bosch IoT Permission (authorization token)
  • identity.bosch.com - formerly allowed for a JSON Web Token issued by Bosch CIAM/eIDP
  • https://identity.bosch.com/ - formerly allowed for a JSON Web Token issued by Bosch CIAM/eIDP
  • accounts.google.com - formerly allowed for a JSON Web Token issued by Google
  • https://accounts.google.com - formerly allowed for a JSON Web Token issued by Google

Connection logs - NEW

The Solutions resource now offers additionally a logs sub-resource.

GET /solutions/{solutionId}/connections/{connectionId}/logs

The Things dashboard already offers to display such log entries

Find details at Manage your connections > log_entries.


Search improvements

The new service release comes with various search improvements:

Among others, the new Search now supports:

  • Various internal fields, which can be used in a search filter, or to be part of your search results
  • New paging options via cursor
    • You can for example limit the first search results to <your-number> items (default 25).
    • The cursor marks the position after the last entry of the previous search to “bookmark” where to start the next set of result.
    • The paging option limit({offset},{count}) is deprecated.
      In case you still use the old option, slow queries or timeouts might occur.
      Also, the old options might be removed without further notice.

At this occasion, various minor bugs have also been fixed.

 

Connection configuration

New placeholders and placeholder functions for configuring connections. While editing the sources and targets of your connection you can make use of them. Find details at Basic concepts >

Suite Auth token - BETA

A new type of Web Token for authorization at the HTTP API, namely Suite Auth token - BETA, is supported

Namespace deletion changes

Since Dec 2018, deletion of a namespace includes the full deletion of all entities within this namespace, such as things, policies, topology schemas and topologies. Deleting the entities will erase them from our data store without an option to restore.

In order to avoid that some authorized subject could delete all data just by trying out our interactive HTTP API documentation, the Solutions resource does not offer any longer the operations:

  • PUT /solutions/{solutionId}/namespaces
    Creates or Updates the namespaces of a Solution
  • DELETE/solutions/{solutionId}/namespaces
    Delete all namespaces of a specific Solution

However, in case you need to delete a namespace, please use the UI. The deletion of a namespace will require a second confirmation by the user. Then, it triggers the full deletion of all entities within this namespace. The progress bar displays an estimation on how long the procedure might need.

Messages to Bosch IoT Hub

Bosch IoT Things is prepared to support the command-and-control pattern of Bosch IoT Hub. This allows business applications to invoke operations on the devices connected via the Hub service.

A message sent via our HTTP Messages resource can be forwarded as a command to a specific Hub address, which you can configure at the connections. The result (from the device, via Hub) is matched to the request via correlation IDs.

As message buffering is not provided. Your message can only be delivered successfully, if the Hub connection is open and a consumer is ready to receive the command at the respective point in time (e.g. within a still open HTTP adapter request timeframe).

Hub-specific configurations (e.g. special reply-to headers, subject headers, source addresses) are prepared by selecting “Bosch IoT Hub” as the connection type in the “new connection wizard”. See Manage your connections.

Open API 3

Our new interactive HTTP API description comes with a new look and feel.

Compared to Swagger version 2, the main difference at the user interface is, that “Try it out” does not submit the request any longer, but only enables the entry fields. Enter at least all “required” parameters and submit the request by clicking “Execute”.

Find details provided by the Swagger team at their online presence:
https://swagger.io/blog/news/whats-new-in-openapi-3-0/

Find our API description at https://apidocs.bosch-iot-suite.com.


Relations deprecated

The HTTP Relations endpoint will be deprecated.
However, in case you still need to preserve some relation information, here are some alternatives:

  • For a simple parent-child-relation - you can use a parent property whithin the child thing instead.
  • For a source-target relation - use the things HTTP endpoint and store the information directy whithin a thing entity.
    The content could be for example the same as the things service has internally used in previouse versions:
      {
        "thingId": "my.namespace:relation-example-01",
        "attributes": {},
        "features": {
          "relation": {
            "properties": {
              "source": "my.namespace:ID-of-the-source-Thing",
              "target": "my.namespace:ID-of-the-target-Thing"
            }
          }
        }
      }
  • For more complex relationships use Topologies - BETA.
 

Conditional requests

Sometimes it is convenient and more fault-tolerant to create, modify or delete Things or elements of Things only if these elements either already exist or not exist or are on a specific revision state prior to the execution of the request. Therefore, we introduced support for “conditional requests” based on RFC-7232.

Using conditional requests, you can define a condition - or a list of conditions - and pass these via headers to the Things service. Our system checks the conditions and only processes the request in case they match.

The supported conditional headers are:

  • If-Match
    Read or write the resource only
    • if the current entity tag matches at least one of the entity tags provided in this header
    • or if the header is * and the entity exists
  • If-None-Match
    Read or write the resource only
    • if the current entity tag does not match any of the entity tags provided in this header
    • or if the header is * and the entity does not exist

Find examples on using such headers at
How to work with conditional requests?

 

New sub-resources for connection management

The solutions resource now additionally provides sub-resources to manage you connections.
See Solutions resources.

Tip: The easy way is to create connections via the user interface Manage your connections.

Enforced limited data volume for Free plans

In case a service subscription for a Free plan exceeds the agreed data volume, further PUT and POST requests are hindered.
However, DELETE requests are still handled, as such actions might help to reduce the data volume and overcome the situation.

Find details on alternative options at FAQ > How to avoid limited data volume?

New Messaging timeout parameter

All sub-resources provide now the optional timeout parameter. (In previous version this was available for claiming messages only). The value defines the time (in seconds) how long to block the HTTP request and wait for a response:

  • Default value (if omitted): 60 seconds.
  • Maximum value: 600 seconds.
  • Minimum value: 0 seconds (i.e. fire-and-forget)

As a result, the Messages resources now support the request-response pattern as well as fire-and-forget semantics.

New Namespace concept

All entities need a specific namespace as a prefix of their ID.
Find a summary at News > Namespaces.

Accordingly we have updated the solutions resource. It can now be used to reserve various namespaces for a solution and to define a default namespace.
See Solutions resources.

The Manage your solution UI was updated respectively to support you on such tasks.

Policy for a JWT as a subject

Setting a JWT issuer as a subject ID prefix is deprecated.

We recommend to adapt your existing policies according to the Policies documentation.

New HTTP API 2

Policy for fine-gained access control

With API 2 the Access Control List is replaced with the Policy. The new concept empowers developers to describe fine-grained policies for a complete Thing or a specific Feature.
Find details at Policies and Policies resources.

Compatibility

In case you have created a Thing with API 1 and try to GET it at API 2:

  • The ACL entries become effective.
  • In the JSON representation you will see no ACL entries nor Policies,
    but with the field selector “_policy” you might be able to see the subject IDs.
  • In case you want the Thing to keep compatibility with the API 1 do not use the /policy resource.
  • Searching should work.

In case you have created a Thing with API 2 and try to GET it at API 1:

  • The Policy entries become effective.
  • In the JSON representation you will see an empty ACL field.
  • You cannot convert to API 1 schema, but will need to use the API 2 to see the subject IDs.
  • Searching will not find the things as they have no ACLs.

New field holding the last modification on a Thing

The new service release comes with improvements regarding the logging of the latest modification of the Thing. The timestamp - in ISO-8601 UTC format - is set on each modification of a Thing an can be found within the _modified field.
Find details at Note on special fields.

New function counting Things

The new service release comes with improvements regarding the scalability of updating the Search index.
Further, we have introduced a new sub-resource to count() the Search results.
Find details at Search resources.

New Namespace Management

The new service release comes with improvements regarding the Namespace management.
You can define a default namespace, thus in case your solution does not explicitly specify a namespace upon Thing creation, the complete thing ID would not be “:yourThingID” but “yourDefaultNamespace:yourThingID” instead.
Find details at Manage your namespace.

Search Relations was replaced with Search Things

With our latest update the Relations are internally mapped to Things (which provide a relation feature).
Find an example at Previous versions > Relations - deprecated.
In case you miss the Search Relations resource, please have look at Search resources.

Technical client authentication

In the previous versions the signature for the authentication as technical client (Authenticate as a technical client) contained for POST and PUT operations the JSON body.
This is no longer the case. If you use technical client authentication with a private key, please remove the body from the signature.

Claiming Message

The service provides a new HTTP API for claiming to enable end-users to claim Things and proof ownership thereof.

post /things/{thingId}/inbox/claim
// Initiates claiming a specific Thing in order to gain access

The concept is described at Claiming.