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)

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.
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
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.)