From 81487fd76d45f13c6de65b3b91367764ef77cc84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20J=C3=A4ckle?= Date: Thu, 1 Aug 2024 16:27:52 +0200 Subject: [PATCH] fix documentation about SSE `_context` projection --- .../main/resources/pages/ditto/httpapi-sse.md | 42 ++++++++++--------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/documentation/src/main/resources/pages/ditto/httpapi-sse.md b/documentation/src/main/resources/pages/ditto/httpapi-sse.md index 611052c87e..632a3d7221 100644 --- a/documentation/src/main/resources/pages/ditto/httpapi-sse.md +++ b/documentation/src/main/resources/pages/ditto/httpapi-sse.md @@ -74,6 +74,28 @@ http://localhost:8080/api/2/things?fields=thingId,attributes {% include tip.html content="The `thingId` should always be included in the `fields` query, otherwise it is no longer visible for which thing the change was made." %} +##### Projecting `_context` + +One special field which can be projected 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 it was +a "merged" or "modified" event. + +To obtain this kind of context information, select the `_context` field as part of `fields`, e.g.: +``` +http://localhost:8080/api/2/things?fields=thingId,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) (even all headers) of the command which caused the event + +It is also possible to select only specific context information, e.g.: `fields=_context/topic,_context/path,_context/value` +in order to exclude the `headers`. + + #### Field enrichment In addition to the fields projection, one can also choose to select [extra fields](basic-enrichment.html) @@ -96,26 +118,6 @@ 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