Edit this page

Ditto provides multiple interfaces for interacting with digital twins, ranging from a REST-like HTTP API to persistent WebSocket connections, Server-Sent Events, and a connectivity layer for integrating external messaging systems.

TL;DR: You interact with Ditto through its HTTP API for request/response operations, the WebSocket API for real-time bidirectional communication, SSE for streaming change notifications, and the Connectivity API for integrating external message brokers.

Overview

Ditto offers four primary interfaces, each suited to different use cases:

Interface Best for Protocol
HTTP API CRUD operations, search, messages REST-like HTTP/HTTPS
WebSocket API Real-time events, bidirectional messaging WebSocket (WSS)
Server-Sent Events Streaming change notifications SSE over HTTP
Connectivity API Integrating message brokers (MQTT, Kafka, AMQP, etc.) Various

How it works

HTTP API

The HTTP API follows REST conventions and provides a resource-based interface for managing Things, Policies, and Connections. You send standard HTTP requests (GET, PUT, POST, PATCH, DELETE) and receive JSON responses.

Use the HTTP API when you need:

  • Simple request/response interactions
  • CRUD operations on Things, Features, Policies, and Connections
  • Searching across Things
  • Sending messages to or from devices
  • Lightweight integration from any programming language

WebSocket API

The WebSocket API provides a persistent, duplex connection using the Ditto Protocol. You establish a single connection and exchange JSON messages in both directions.

Use the WebSocket API when you need:

Server-Sent Events (SSE)

SSE provides a unidirectional stream from Ditto to your client. You open a connection and receive events whenever digital twins change or when streaming search results.

Use SSE when you need:

  • Simple, one-way change notifications without WebSocket complexity
  • Streaming search result sets
  • Browser-based event consumption via the standard EventSource API

Connectivity API

The Connectivity API connects Ditto to external messaging systems like MQTT, Apache Kafka, AMQP 1.0, and AMQP 0.9.1. This enables integration with devices and backend systems that communicate through message brokers.

Use the Connectivity API when you need:

  • Integration with existing messaging infrastructure
  • Horizontal scaling of event consumers
  • Round-robin dispatching of messages across multiple consumers

Channel: twin vs. live

Ditto supports two communication channels across all interfaces:

Channel Description
twin (default) Communicates with the persisted digital twin representation
live Communicates directly with the actual device

When you use the live channel, the device itself handles the command. If the device does not respond within the configured timeout (default: 10 seconds), Ditto returns 408 Request Timeout. Ditto performs authorization checks and filters responses based on the Thing’s Policy.

For details, see Ditto Protocol twin/live channel.

Content type

The HTTP API supports application/json for all resources except PATCH operations, which require application/merge-patch+json.

Feature comparison

Feature HTTP API WebSocket SSE Connectivity
Things management (CRUD) Yes Yes – Yes
Features management Yes Yes – Yes
Search Yes Yes Yes (streaming) –
Count Yes – – –
Messages Yes (send) Yes (send + receive) Yes (receive) Yes
Change notifications Yes (SSE) Yes Yes Yes
Policy-based access control Yes Yes Yes Yes
Horizontal scaling – – – Yes

Authentication

All interfaces support:

  • HTTP Basic Authentication with a user managed by an upstream reverse proxy (e.g., nginx)
  • JSON Web Token (JWT) issued by an OpenID Connect provider

See Authentication for details.

Further reading

Tags: http