Skip to content

Latest commit

 

History

History
178 lines (120 loc) · 8.11 KB

httpapi-protocol-bindings-websocket.md

File metadata and controls

178 lines (120 loc) · 8.11 KB
Raw
title keywords tags permalink
WebSocket protocol binding
binding, protocol, websocket, http
protocol
http
rql
httpapi-protocol-bindings-websocket.html

Ditto Protocol messages can be sent as is as WebSocket message. The Ditto Protocol JSON must be sent as UTF-8 encoded String payload.

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

From then on the WebSocket session will receive all change notifications it is entitled to see.

Request messages

In order to subscribe for messages which can be sent from a WebSocket session to another WebSocket session or from the HTTP API to a WebSocket session, the following text message has to be sent to the backend: START-SEND-MESSAGES

From then on the WebSocket session will receive all messages it is entitled to see.

Request live commands

In order to subscribe for live commands which can be sent from a WebSocket session to another WebSocket session, the following text message has to be sent to the backend: START-SEND-LIVE-COMMANDS

From then on the WebSocket session will receive all live commands it is entitled to see.

Request live events

In order to subscribe for live events which can be sent from a WebSocket session to another WebSocket session, the following text message has to be sent to the backend: START-SEND-LIVE-EVENTS

From then on the WebSocket session will receive all live events it is entitled to see.

Overview

The following table shows which WebSocket protocol message are supported:

Description Request message Response message
Subscribe for events/change notifications START-SEND-EVENTS START-SEND-EVENTS:ACK
Stop receiving change notifications STOP-SEND-EVENTS STOP-SEND-EVENTS:ACK
Subscribe for messages START-SEND-MESSAGES START-SEND-MESSAGES:ACK
Stop receiving messages STOP-SEND-MESSAGES STOP-SEND-MESSAGES:ACK
Subscribe for live commands START-SEND-LIVE-COMMANDS START-SEND-LIVE-COMMANDS:ACK
Stop receiving live commands STOP-SEND-LIVE-COMMANDS STOP-SEND-LIVE-COMMANDS:ACK
Subscribe for live events START-SEND-LIVE-EVENTS START-SEND-LIVE-EVENTS:ACK
Stop receiving live commands STOP-SEND-LIVE-EVENTS STOP-SEND-LIVE-EVENTS:ACK

Filtering

In order to only consume specific events like described in change notifications, the following parameters can additionally be provided when sending the WebSocket protocol messages:

Description Request message Filter by namespaces Filter by RQL expression
Subscribe for events/change notifications START-SEND-EVENTS ✔ ✔
Subscribe for messages START-SEND-MESSAGES ✔ ❌
Subscribe for live commands START-SEND-LIVE-COMMANDS ✔ ❌
Subscribe for live events START-SEND-LIVE-EVENTS ✔ ✔

The parameters are specified similar to HTTP query parameters, the first one separated with a ? and all following ones with &. You have to URL encode the filter values before using them in a configuration.

For example this way the WebSocket session would register for all events in the namespace org.eclipse.ditto and which would match an attribute "counter" to be greater than 42:

START-SEND-EVENTS?namespaces=org.eclipse.ditto&filter=gt(attributes/counter,42)