Proposal on a mildly breaking change

I hate to call it a breaking change as it would only affect people who
build uris on their own and don't use rel links but it would be
breaking in that case. If this might affect you please feel free to
comment either here or on the github issue.

https://github.com/EventStore/EventStore/issues/424

OK I have been thinking a lot about this issue as I am strongly of the
belief we will want to support additional protocols in the future (SSE
or EventSource as examples for live subscriptions). We also have
competing. All of these things are being added in a hodge podge way
due to us (me?) originally deciding that the /streams/{stream} uri
should point to an atom feed.

In an ideal world as mentioned above /streams/{stream} would point to
a description document that may look something like:

A client would then choose how they wished to interact.

Obviously the issue with this is that the above change would be a very
large breaking change and would break basically anyone using the HTTP
api (including ourselves). I think however there is a reasonable path
to implement the change.

/streams/foo no accept/unknown accept -> description document
/streams/foo Accept: vnd.eventstore.stream_description -> description document
/streams/foo Accept: application/atom+xml 301 location /streams/foo/atom
/streams/foo Accept: application/vnd.eventstore.atom+json 301 location
/streams/foo/atom
/streams/foo Accept: text/event-stream 301 location /streams/foo/sse

Impact of changes

For people that have followed the rules (e.g. following rel links
instead of building their own) their code would continue to work so
long as they understood a redirect which I consider to be a reasonable
assumption. They could add support for the description document at
their leisure.

For people who have not followed the rules and self-build uris this
would be a breaking change. I think this is actually reasonable as
from the beginning the docs have been littered with warnings of "don't
bookmark these uris as they may change in the future, use the rel
links).

Work Involved
I can do most of the work around this relatively quickly. The more of
a PITA part about it is that we don't necessarily follow the rules in
many of our unit tests around http (for obvious reasons). As such
there will likely be a few hundred broken tests as part of this
change. Documentation would also need to be updated somewhat (mostly
the reading streams page and http getting started doc).

At the end however we would be left with a much nicer interface overall.

Cheers,

Greg

Perhaps you can also add a switch to go back to the current behaviour? To make it possible to migrate over to using the rel links for anyone who has been building the uri’s on their own.

There would be a switch. Just set accept headers on your request and
everything should just keep working for you?

To be clear I am not using this. Seems like a good approach though.

To be clear the only people who would break...

1) Do not send an accept header (default would change)
2) Dont understand redirects

I think #2 is a pretty reasonable expectation? Maybe its not with some
libraries?

For #1 it would just be to add an Accept: application/atom+xml etc on
the request