WebSocket features

The WebSocket provides an alternative to the HTTP API in order to manage your Digital Twins.

The benefits of the WebSocket compared to HTTP are multiple ones:

a single connection (socket like) is established and for commands to Digital Twins no further HTTP overhead (e.g. HTTP headers, HTTP connection establishment) is produced which means you can get more commands/seconds through the WebSocket compared to the HTTP endpoint
as the WebSocket is a duplex connection, change notifications can be sent via the WebSocket for changes to entities done in Ditto
additionally, messages and live commands/events can be exchanged (sending and receiving) via multiple connected WebSocket sessions

Send commands and get responses

When sending a command via WebSocket you will receive a corresponding response (the response can be related to the request by the correlation-id header).
The response indicates the success or the failure of the command and, depending on the command type, contains the result payload.

Please find examples of commands and their response pattern at Protocol examples.

Request receiving events/change notifications

In addition to the response, which Ditto addresses directly to the instance which was sending the command, an event is generated.
This will be delivered to all other clients with read permissions for the respective thing, feature change, etc.

See request events for subscribing/unsubscribing for receiving change notifications.

Request receiving messages

Messages can be sent both via the HTTP API and the WebSocket. Receiving messages and answering to them however can only be done via the WebSocket.

See request messages for subscribing/unsubscribing for receiving messages.

Request receiving live commands + events

In order to receive live commands and events, the WebSocket API can be used. The Ditto Protocol messages are the same as for the "twin" channel, only with live as channel in the topic.

See request live commands and request live events for subscribing/unsubscribing for receiving live commands and events.

WebSocket endpoint

The WebSocket endpoint is accessible at these URLs (depending on which API version to use):

ws://localhost:8080/ws/1
ws://localhost:8080/ws/2

Authentication

A user who connects to the WebSocket endpoint can be authenticated by using

HTTP BASIC Authentication by providing a username and the password of a user managed within nginx or
a JSON Web Token (JWT) issued by an OpenID connect provider.

See Authenticate for more details.

WebSocket protocol format

As defined in the Protocol specification a Ditto Protocol message consists of different information. This information is combined into a single JSON message for the WebSocket endpoint:

topic: JSON string with key topic
headers: JSON object with key headers
path: JSON string with key path
value: JSON value (e.g. JSON object, string, array, ...) with key value
status (for responses): JSON number with key status

The schema for Ditto Protocol message via WebSocket:

{
  "topic": "<the topic>",
  "headers": {
    "correlation-id": "<a correlation-id>",
    "a-header": "<header value>"
  },
  "path": "<the path>",
  "value": {
    
  }
}

WebSocket binding specific messages

The WebSocket binding defines several specific messages which are not defined in the Ditto Protocol specification.

Those are also not defined as JSON messages, but as plain text messages. All of those declare a demand for some kind of information from the backend to be pushed into the WebSocket session.

Request events

In order to subscribe for events/change notifications for entities (e.g. Things), following text message has to be sent to the backend:

START-SEND-EVENTS