Which API to use?
Bosch IoT Things service provides various ways to interact:
- A REST-like HTTP API endpoint
with a sophisticated resource layout, that allows to create, read, update and delete Things and the Thing's data. - A Things Java Client
which implements our API to communicate with the Things service in Java. The client itself uses the WebSocket protocol.
- A WebSocket endpoint for interacting based on the Eclipse Ditto protocol
- Data ingestion and device control via the Bosch IoT Hub service
based on AMQP 1.0. - Managed connections to external messaging/communication endpoints - based on Eclipse Ditto protocol or using payload mapping:
- connecting to HTTP endpoints POST, PUT or PATCH requests
- connecting to Advanced Message Queuing Protocol (AMQP) brokers
(currently we support AMQP 0.9.1 and AMQP 1.0) - connecting to Message Queuing Telemetry Transport (MQTT) brokers
(currently we support MQTT 3.1.1) - connecting to Apache Kafka
(currently we support Kafka 2.x)
HTTP API, Java client, WebSocket, AMQP, MQTT or Kafka?
All these ways are nearly equally powerful and allow the same operations to work with the Thing's data, send messages to Things and receive messages from Things.
- The lightweight REST-like HTTP API can be used
- on less powerful devices lacking a Java runtime or supporting other (scripting) languages like JavaScript, Python, C/C++,
- and for developing Web-based user interfaces.
- The Things Client is mainly targeted to environments which support a Java runtime to implement, for example
- a device integration layer on a hub/gateway,
- a rich client,
- or a cloud service of a custom solution.
- The plain WebSocket channel proves useful for
- gathering data streams from devices or massive data from another message broker
- real-time device monitoring,
- event-driven Web applications,
- full duplex communication scenarios, etc.
- Connections to AMQP message brokers might be a good option for
- frequently receiving telemetry data from a message broker
like RabbitMQ (AMQP 0.9.1) or the Bosch IoT Hub (supports AMQP 1.0), - connecting applications across different platforms,
- message-driven workflows, etc.
- Connections to MQTT message brokers might be a good option for constrained environments, where a small code footprint is required and network bandwidth is limited.
- Connections to HTTP servers/endpoints might be a good option for publishing e.g. twin events by triggering webhooks, which should be notified about twin changes.
- Connections to Apache Kafka can be used for building real-time data pipelines and streaming apps.
Currently the Things service only supports publishing to Apache Kafka via targets (but not consuming from it via sources).
You can publish twin events, messages, live commands and events to Kafka topics.
Comparison by feature
| Feature | Things HTTP API | Things Client (Java) | Things protocol over WebSocket | Things protocol over AMQP | Things protocol over MQTT | Things protocol to Apache Kafka | Things protocol to HTTP endpoint |
|---|---|---|---|---|---|---|---|
| Things management | ✓ | ✓ | ✓ | ✓ | ✓ | no | no |
| Twin channel | ✓ | ✓ | ✓ | ✓ | ✓ | no | no |
| Live channel | no | ✓ | ✓ | ✓ | ✓ | no | no |
| Features management | ✓ | ✓ | ✓ | ✓ | ✓ | no | no |
| Definitions | ✓ | ✓ | ✓ | ✓ | ✓ | no | no |
| Policy management | ✓ | no | no | no | no | no | no |
| Search Things | ✓ | no | no | no | no | no | no |
| Count Things | ✓ | no | no | no | no | no | no |
| Messages | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (one way w/o response) | ✓ (one way w/o response) |
| Subscriptions | no | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Solutions management | ✓ | no | no | no | no | no | no |
| Namespaces mgmt. | ✓ | no | no | no | no | no | no |
| Connections mgmt. | ✓ | no | no | no | no | no | no |
| Payload mapping | no | no | no | ✓ | ✓ | ✓ | ✓ |
Further aspects in which the interfaces differ
| Criteria | Things HTTP API | Things Client (Java) | Things protocol over WebSocket | Things protocol over AMQP | Things protocol over MQTT | Things protocol to Apache Kafka | Things protocol to HTTP endpoint |
|---|---|---|---|---|---|---|---|
| Programming language | Almost any programming language, e.g. Java, JavaScript, NodeJS, .NET, Python, C/C++ | Java | Almost any Web oriented programming language, e.g. Java, JavaScript, .NET | Almost any programming language, as long as an AMQP client is available. | Almost any programming language, as long as an MQTT client is available. | Almost any programming language, as long as Kafka supports it. | Almost any programming language capable of starting an HTTP server. |
| Connection paradigm | Connectionless protocol with lower permanent resource allocation on sporadic transactions | Connection-oriented with an always open and persistent connection with only one-time handshake overhead for lowest latency and highest throughput | Connection-oriented with an always open and persistent connection with only one-time handshake overhead for lowest latency and highest throughput. | Connection-oriented with a persistent connection, which can be opened or closed on demand. | Connection-oriented with a persistent connection, which can be opened or closed on demand. | Connection-oriented with a persistent connection, which can be opened or closed on demand. | Connectionless protocol: for each outgoing message one HTTP request is done. |
| Channel security | HTTPS HTTP over Transport Layer Security | WSS WebSocket over Transport Layer Security | WSS WebSocket over Transport Layer Security | AMQPS AMQP over Transport Layer Security | SSL MQTT over Transport Layer Security | SSL over Transport Layer Security | HTTPS HTTP over Transport Layer Security |
| Message exchange pattern | blocking request - response | non-blocking request - asynchronous response | non-blocking request - asynchronous response | non-blocking request - asynchronous response | non-blocking request - asynchronous response | non-blocking request (no response supported as of today) | blocking request - response |
| Authentication mechanism | ✔ User authentication using: HTTP BASIC Authentication, Identity Context based on Bosch IoT Permissions, JSON Web Token (JWT) issued by the Bosch IoT Permissions service, Bosch-ID or Google see Authenticate as a user ✔ Technical client authentication using cryptographic signature see Authenticate as a technical client | ✔ User authentication using: HTTP BASIC Authentication ✔ Technical client authentication using cryptographic challenge-response mechanism see Things-Client instantiation and usage | ✔ User authentication using: HTTP BASIC Authentication, Identity Context based on Bosch IoT Permissions, JSON Web Token (JWT) issued by the Bosch IoT Permissions service, Bosch-ID or Google ✔ Technical client authentication using cryptographic signature see WebSocket binding | ✔ User authentication (with username and password) | ✔ User authentication (with username and password) ✔ Client certificate authentication | ✔ User authentication (with username and password) | ✔ User authentication (with username and password) |
| Equivalent available in open source Eclipse Ditto | Based on Eclipse Ditto, but additional resource here (e.g. Solution) | no | The complete protocol is defined in Eclipse Ditto. | The complete protocol is defined in Eclipse Ditto. Additionally, for AMQP messages Ditto provides payload mapping functionality. (You can map incoming messages to Eclipse Ditto conform payload and vice versa.) | The complete protocol is defined in Eclipse Ditto. Additionally, for MQTT messages Ditto provides payload mapping functionality. (You can map incoming messages to Eclipse Ditto conform payload and vice versa.) | The complete protocol is defined in Eclipse Ditto. Additionally, for Apache Kafka messages Ditto provides payload mapping functionality. (You can map outgoing messages to Eclipse Ditto conform payload.) | The complete protocol is defined in Eclipse Ditto. Additionally, for outgoing HTTP messages Ditto provides payload mapping functionality. (You can map outgoing messages to Eclipse Ditto conform payload.) |