Description document

With the addition of Competing Consumers, which is 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 EventStoreDB and you can rely on it as a lookup for the particular method of reading a stream.
• Allows the restructuring of URIs underneath without breaking clients. e.g., /streams/newstream -> /streams/newstream/atom.

Fetching the description document

There are three ways in which EventStoreDB returns the description document.

• 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 accept header, for example:

curl -i http://localhost:2113/streams/newstream \
    -H "accept:application/vnd.eventstore.streamdesc+json"

HTTP/1.1 200 Description Document
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-Forwarded-Host, X-Forwarded-Prefix, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTos
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position, ES-CurrentVersion
Content-Type: application/vnd.eventstore.streamdesc+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Thu, 23 Aug 2018 12:37:18 GMT
Content-Length: 517
Keep-Alive: timeout=15,max=100

{
  "title": "Description document for 'newstream'",
  "description": "The description document will be presented when no accept header is present or it was requested",
  "_links": {
    "self": {
      "href": "/streams/newstream",
      "supportedContentTypes": [
        "application/vnd.eventstore.streamdesc+json"
      ]
    },
    "stream": {
      "href": "/streams/newstream",
      "supportedContentTypes": [
        "application/atom+xml",
        "application/vnd.eventstore.atom+json"
      ]
    }
  }
}

// Make sure to add code blocks to your code group

In the example above, the client requested the description document for the stream called newstream which has a set of links describing the supported methods and content types. The document also includes additional methods available such as the streamSubscription. If there are no subscriptions to the newstream, the streamSubscription key is absent.