stream_id as a path parameter instead of a query parameter in event stream management endpoints
Closed this issue · 7 comments
In sections 7.1.1.2, 7.1.1.4, and 7.1.2 the event stream endpoints accept stream_id as a query parameter. The REST standard recommend that immutable fields like stream_id be part of the URL path not query parameters. We should consider changing the spec to use the standard notation.
There might be an issue with existing implementations that already assume that the stream_id is passed as a query parameter but most HTTP binding frameworks make such a change easy to make.
This will majorly break compatibility with existing implementations. We should avoid this at this point
I was going to comment on this too. Using queries when a URL path would do is preferred for me. Why would you have a query parameter when you aren't doing a search (esp on PUT, PATCH operations)
I think a filter also implies a lot of functionality which isn't there right now. E.g. can a filter be based on other attributes?
By having config id as a path element then we're not implying a search function and the spec is simpler.
Yes, it is a breaking change, but this is why we go through this review cycle.
The biggest reason we chose to use a query parameter instead of a path parameter was because there is not an easy standard for how the path parameter should be written as a variable. The transmitter must supply a transmitter config which lists the URLs for stream management. These URLs must apply to all streams, so having a URL that changes based on the id of the stream is challenging to write in a standard format that all receivers can parse.
Perhaps there is some standard I am unaware of though?
It is extremely common to use /streams/<stream_id>
What is nice about this is it becomes a permanent URI. If for some reason a deployment changed, and/or a new steam_id had to be issued, it would be easy to redirect to the new address.
By using a query, the functionality of query seems like it is supported when the spec is silent. So if someone does get /streams?iss=example.com what would be the response?
I think what concerns me most about using a filter mechanism to select a stream is that it prevents any natural evolution SSF that might support queries in the future (the ability to find one or more streams based on some criteria). Any such desire would cause a necessary breaking change.
Ok...so a lot won't need this functionality. However, I thought the point of interoperable administration was precisely because of concerns about managing many streams. In this sense, the clients to SSF are not just receivers, but shell scripts, continuous deployment systems and web administration and provisioning services.
I would much rather have a breaking change today (using /stream/<stream_id> ) so that those that want query capability can add it.
Since this will break compatibility, I'd like to close this issue. Please re-open if you feel we need to work on this.
I would prefer id be in the path for consistency with most other apis.
We are not at implementers draft so it is changeable.
Also by not encumbering query, search or confirmation is possible in future (or much less complex).
SCIM uses path based identifiers and many have commented that permanent URIs for objects is a big benefit.