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)

things connections

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.
  • 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
  • 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
  • Ditto client (Java)
  • Ditto client (JavaScript)
  • Things protocol over WebSocket
  • 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.)
Corporate information Data protection notice Legal information Support Free plans