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

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 and 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 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 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 Ditto Java client Ditto JavaScript client Things Java client
deprecated
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
Definition no no no
Features management no no
Feature Definitions no no
Policy management no no no no no no
Search things soon no no soon no no no no
Count things no no no no no no no no
Messages ✓ (one way w/o response) ✓ (one way w/o response)
Event notifications no
Solutions management no no no no no no no no
Namespaces management no no no no no no no no
Connections management no no no no no no no no
Payload mapping 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/Things client (Java)
    Java
  • Ditto JavaScript client
    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/Things client (Java)
    Connection-oriented with an always open and persistent connection with only one-time handshake overhead for lowest latency and highest throughput
  • Ditto JavaScript client
    Choose between:
    • 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.
  • Things protocol over WebSocket
    Connection-oriented with an always open and persistent connection with only one-time handshake overhead for lowest latency and highest throughput.
  • Things protocol over AMQP
    Connection-oriented with a persistent connection, which can be opened or closed on demand.
  • Things protocol over MQTT
    Connection-oriented with a persistent connection, which can be opened or closed on demand.
  • Things protocol to Apache Kafka
    Connection-oriented with a persistent 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/Things client (Java)
    WSS - WebSocket over Transport Layer Security
  • Ditto JavaScript client
    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/Things client (Java)
    non-blocking
    request - asynchronous response
  • Ditto JavaScript client
    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
    • 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 client
  • Ditto client (Java)
    • User authentication using: HTTP BASIC Authentication
    • Technical client authentication using OAuth2 JWAT-authentication
      see ditto-client instantiation
  • Ditto JavaScript client
  • Things client (Java)
    • User authentication using: HTTP BASIC Authentication
    • Technical client authentication using cryptographic challenge-response mechanism
      see things-client instantiation
  • Things protocol over WebSocket
    • 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 WebSocket binding
  • Things protocol over AMQP
    • User authentication (with username and password)
  • Things protocol over MQTT
    • User authentication (with username and password)
    • Client certificate authentication
  • Things protocol to Apache Kafka
    • User authentication (with username and password)
  • Things protocol to HTTP endpoint
    • User authentication (with username and password)

… 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 JavaScript client
    The complete client is part of Eclipse Ditto.
  • Things client (Java)
    no
  • 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.)
Imprint Legal info Privacy statement