From 3cc6bb9038f8f352434a27796ff9acd4651d50de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20J=C3=A4ckle?= Date: Sun, 15 Oct 2023 21:03:27 +0200 Subject: [PATCH] added documentation for SSE "_context" extraField MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Thomas Jäckle --- .../pages/ditto/connectivity-mapping.md | 1 + .../main/resources/pages/ditto/httpapi-sse.md | 21 +++++++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/documentation/src/main/resources/pages/ditto/connectivity-mapping.md b/documentation/src/main/resources/pages/ditto/connectivity-mapping.md index b5e76933c0..c35713afc5 100644 --- a/documentation/src/main/resources/pages/ditto/connectivity-mapping.md +++ b/documentation/src/main/resources/pages/ditto/connectivity-mapping.md @@ -129,6 +129,7 @@ would result in the following normalized JSON representation: "_context": { "topic": "thing/id/things/twin/events/modified", "path": "/features/sensors/properties/temperature/indoor/value", + "value": 42, "headers": { "content-type": "application/json" } diff --git a/documentation/src/main/resources/pages/ditto/httpapi-sse.md b/documentation/src/main/resources/pages/ditto/httpapi-sse.md index 7f6ecdd6a9..611052c87e 100644 --- a/documentation/src/main/resources/pages/ditto/httpapi-sse.md +++ b/documentation/src/main/resources/pages/ditto/httpapi-sse.md @@ -96,6 +96,27 @@ An example without filtering would look like this: http://localhost:8080/api/2/things?fields=thingId,attributes&extraFields=attributes ``` +##### Enriching `_context` + +One special field which can be enriched for the SSE is the `_context` field. +As the SSE format returns a "normalized" view in form of the [thing JSON]( basic-thing.html#model-specification) +of change events, some "context" of the event gets lost, e.g. on which `path` the event was issued or whether is was +a "merged" or "modified" event. + +To obtain this kind of context information, select the `_context` field as `extraFields`, e.g.: +``` +http://localhost:8080/api/2/things?fields=thingId,attributes&extraFields=attributes,_context +``` + +The `_context` will contain: +* `topic`: the [Ditto Protocol topic](protocol-specification.html#topic) +* `path`: the [Ditto Protocol path](protocol-specification.html#path) +* `value`: the [Ditto Protocol value](protocol-specification.html#value) +* `headers`: the [Ditto Protocol headers](protocol-specification.html#headers) + +It is also possible to select only specific context information, e.g.: `extraFields=_context/topic,_context/path,_context/value` +in order to exclude the `headers`. + #### Filtering by namespaces As described in [change notifications](basic-changenotifications.html#by-namespaces), it is possible to subscribe only