What is it?
With the addition of Competing Consumers which is essentially another way of reading streams, the need arose to expose these different methods to consumers.
The introduction of the description document has some benefits
- Clients can rely on the keys (streams, streamSubscription) in the description document to remain unchanged across versions of Event Store and can be relied on as a lookup for the particular method of reading a stream.
- Allows the restructuring of URIs underneath without breaking clients. e.g.
How do I get the description document?
There are 3 ways in which the description document will be returned.
- Attempting to read a stream with an unsupported media type.
- Attempting to read a stream with no accept header.
- Requesting the description document explicitly.
The client is able to request the description document by passing
application/vnd.eventstore.streamdesc+json in the
curl -i http://localhost:2113/streams/newstream -H "accept:application/vnd.eventstore.streamdesc+json"
In the example above, the client has requested the description document for the stream called
newstream which has a set of links which describes the supported methods and content types for reading.
The document also includes additional methods if they are available such as the
streamSubscription (Which is HTTP Competing Consumers). What is displayed in the example above is that there are 2 subscriptions for the
competing_consumers_group2. If there are no subscriptions to the
streamSubscription key will be absent.