Which API to use?
Bosch IoT Things service provides various ways to interact:
- A REST-like HTTP API
with a sophisticated resource layout, that allows to create, read, update and delete Things and the Thing’s data. - A Ditto Java client
which implements our API to communicate with the Things service in Java. The client itself uses the WebSocket protocol. - A Ditto JavaScript client, which can use the WebSocket protocol or the REST-like HTTP API.
- A WebSocket endpoint for interacting based on the Eclipse Ditto protocol
- Data ingestion and device control via Bosch IoT Hub connection - 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 and MQTT 5)
- 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 Ditto 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 Ditto JavaScript client is mainly targeted to
- Web applications, which need to access the service API directly at the frontend,
- and environments, which support a JavaScript runtime.
- 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.
- frequently receiving telemetry data from a message broker
- 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 supports publishing to Apache Kafka via targets and consuming from Apache Kafka via sources.
You can publish twin events, messages, live commands and events to Kafka topics.
Comparison by feature
Feature | Things HTTP API | Ditto Java client | Ditto JavaScript client | Things protocol over WebSocket |
Things protocol over AMQP |
Things protocol over MQTT |
Things protocol to Apache Kafka |
Things protocol to/from HTTP endpoint |
---|---|---|---|---|---|---|---|---|
Things management | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | no |
Twin channel | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | no |
Live channel | no | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | no |
Definition | ✓ | ✓ | no | ✓ | ✓ | ✓ | ✓ | no |
Features management | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | no |
Feature Definitions | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | no |
Policy management | ✓ | ✓ | no | ✓ | ✓ | ✓ | ✓ | no |
Search things | ✓ | ✓ | no | ✓ | ✓ | ✓ | ✓ | no |
Count things | ✓ | no | no | no | no | no | no | no |
Messages | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (one way w/o response) |
Event notifications | no | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Solutions management | ✓ | no | no | no | no | no | no | no |
Namespaces management | ✓ | no | no | no | no | no | no | no |
Connections management | ✓ | no | no | no | no | no | no | no |
Payload mapping | no | no | no | no | ✓ | ✓ | ✓ | ✓ |
Horizontal scaling | ✓ | no | no | no | ✓ | ✓ | ✓ | ✓ |
SSH tunneling | no | no | no | no | ✓ | ✓ | no | ✓ |
Further aspects in which the interfaces differ, compared by …
… programming language
- Things HTTP API
Almost any programming language, e.g. Java, JavaScript, NodeJS, .NET, Python, C/C++ - Ditto client (Java)
Java - Ditto client (JavaScript)
TypeScript - Things protocol over WebSocket
Almost any Web oriented programming language, e.g. Java, JavaScript, .NET - Things protocol over AMQP
Almost any Web oriented programming language, e.g. Java, JavaScript, .NET - Things protocol over MQTT
Almost any programming language, as long as an MQTT client is available. - Things protocol to Apache Kafka
Almost any programming language, as long as Kafka supports it. - Things protocol to HTTP endpoint
Almost any programming language capable of starting an HTTP server.
… connection paradigm
- Things HTTP API
Connectionless protocol with lower permanent resource allocation on sporadic transactions - Ditto client (Java)
Connection-oriented with an always open and managed connection with only one-time handshake overhead for lowest latency and highest throughput - Ditto client (JavaScript)
Choose between:- Connectionless protocol with lower permanent resource allocation on sporadic transactions
- Connection-oriented with an always open and managed connection with only one-time handshake overhead for lowest latency and highest throughput.
- Things protocol over WebSocket
Connection-oriented with an always open and managed connection with only one-time handshake overhead for lowest latency and highest throughput. - Things protocol over AMQP
Connection-oriented with a managed connection, which can be opened or closed on demand. - Things protocol over MQTT
Connection-oriented with a managed connection, which can be opened or closed on demand. - Things protocol to Apache Kafka
Connection-oriented with a managed connection, which can be opened or closed on demand. - Things protocol to HTTP endpoint
Connectionless protocol: for each outgoing message one HTTP request is done.
… channel security
- Things HTTP API
HTTPS - HTTP over Transport Layer Security - Ditto client (Java)
WSS - WebSocket over Transport Layer Security - Ditto client (JavaScript)
HTTPS - HTTP over Transport Layer Security
WSS - WebSocket over Transport Layer Security - Things protocol over WebSocket
WSS - WebSocket over Transport Layer Security - Things protocol over AMQP
AMQPS - AMQP over Transport Layer Security - Things protocol over MQTT
SSL - MQTT over Transport Layer Security - Things protocol to Apache Kafka
SSL - over Transport Layer Security - Things protocol to HTTP endpoint
HTTPS - HTTP over Transport Layer Security
… message exchange pattern
- Things HTTP API
blocking
request - response - Ditto client (Java)
non-blocking
request - asynchronous response - Ditto client (JavaScript)
Choose between:- blocking
request - response - non-blocking
request - asynchronous response
- blocking
- Things protocol over WebSocket
non-blocking
request - asynchronous response - Things protocol over AMQP
non-blocking
request - asynchronous response - Things protocol over MQTT
non-blocking
request - asynchronous response - Things protocol to Apache Kafka
non-blocking
request (no response supported as of today) - Things protocol to HTTP endpoint
blocking
request - response
… authentication mechanism
- Things HTTP API
- User authentication using OAuth2 see authenticate as a user
- Ditto client (Java)
- Technical client authentication using OAuth2 client credentials.
see ditto-client instantiation
- Technical client authentication using OAuth2 client credentials.
- Ditto client (JavaScript)
- User authentication using: HTTP BASIC Authentication
see Client SDK JavaScript
- User authentication using: HTTP BASIC Authentication
- Things protocol over WebSocket
- User authentication using OAuth2 see authenticate as a user
- Things protocol over AMQP
- User authentication with username and password
- Things protocol over MQTT
- User authentication with username and password
- Technical client authentication using certificates
- Things protocol to Apache Kafka
- User authentication with username and password
- Things protocol to HTTP endpoint
- User authentication with username and password
- Technical client authentication using certificates
… equivalent available in open source Eclipse Ditto
- Things HTTP API
Based on Eclipse Ditto, but additional resource here (e.g. Solution) - Ditto client (Java)
The complete client is part of Eclipse Ditto. - Ditto client (JavaScript)
The complete client is part of Eclipse Ditto. - Things protocol over WebSocket
The complete protocol is defined in Eclipse Ditto. - Things protocol over AMQP
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.) - Things protocol over MQTT
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.) - Things protocol to Apache Kafka
The complete protocol is defined in Eclipse Ditto.
Additionally, for Apache Kafka messages Ditto provides payload mapping functionality.
(You can map incoming messages to Eclipse Ditto conform payload and vice versa.) - Things protocol to HTTP endpoint
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.)