Skip to content

Commit

Permalink
added documentation for SSE "_context" extraField
Browse files Browse the repository at this point in the history
Signed-off-by: Thomas Jäckle <thomas.jaeckle@beyonnex.io>
  • Loading branch information
thjaeckle committed Oct 15, 2023
1 parent 9c76cd3 commit 3cc6bb9
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 0 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
Expand Down
21 changes: 21 additions & 0 deletions documentation/src/main/resources/pages/ditto/httpapi-sse.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 3cc6bb9

Please sign in to comment.