On Wed, May 01, 2019 at 08:10:47PM +0200, Carsten Bormann wrote:
>
> > While I agree that I'd rather not see a version number in URIs if I
> > don't have to, I don't think there's much of a moral difference
> > between /api/vN/... and {/api/..., /apivN/...}. Both end up with
> > version numbers in the URI local-part components, with the second
> > case avoiding them only for the first version — hardly a huge win.
>
> There is no technical difference, but there is a big difference in signaling.
> /api/v1 is just an affordance that is inviting you to exercise it.
> As in “This protocol is designed to have many incompatible versions”.
That's very subjective. I still see no difference. I'm not defending
versions in URI local-parts -- I dislike that as much as anyone on this
thread.
> There is a strong tendency of trying to transfer the experience from
> software versions to protocol versions. The former are useful (and
> there is a de-facto standard for how to handle the numbering), the
> latter rarely are — a “protocol version” is mainly there to prevent
> communication (and even in the cases where the original design was
> actually considering evolution, the deployment experience often still
> is exactly that).
Protocol and implementation versioning are generally decoupled, but
protocols do need to evolve -- sometimes radically, but yes, backwards-
compatible evolution is always preferable.
> > Or register and use a new header to communicate version numbers.
> > Maybe we should have standard, generic API version
> > negotiation/indication headers?
>
> I hope not.
>
> Kick the habit. Stop thinking in versions. There are better ways to
> handle evolution.
Tell Michael :) If I had to version an API, I'd consider using MIME
types and Accept/Content-Type, as I mentioned.
