Skip to content

Commit

Permalink
fix documentation about SSE _context projection
Browse files Browse the repository at this point in the history
  • Loading branch information
thjaeckle committed Aug 1, 2024
1 parent c55c0a0 commit 81487fd
Showing 1 changed file with 22 additions and 20 deletions.
42 changes: 22 additions & 20 deletions documentation/src/main/resources/pages/ditto/httpapi-sse.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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

Expand Down

0 comments on commit 81487fd

Please sign in to comment.