>this should be a simple call, where an API returns its capabilities early
on
I agree and I think this meshes with the "per endpoint" vs "global" API
version discussion. Client migration will not be eased by having to to
detect available APIs on every endpoint; so if we're doing versioning for
that reason I really think it needs to be global. Global versioning will
also prevent de-coupling of the API versioning from release versions which
I think is important for restricting breaking API changes within a major
release. Whilst that could be accommodated by including even more API
versions in any given release I think the complexity of such an approach
multiples too rapidly.
To that end I also think that if the primary driver for API versioning is
to make migration easier then the default behaviour of the API (whether
that be by header or path or whatever mechanism) must be v3 compatibility
and that "v4" behavior must be specifically requested. As Joan said:
>Namely: if I point a CouchDB 1.x-3.x client at a future CouchDB 4.0, I
>shouldn't be *too* surprised, and as much as possible should "just
>work."
There have been a lot of great potential benefits of versioning listed in
this thread. However, I am concerned that there are split objectives of
why we might want API versioning. Specifically I think it might help to
choose whether we want versioning primarily either to ease migration or
for maximum future flexibility to evolve APIs. I think those two goals are
broadly incompatible in the sense that the best solution for one will
either end up hindering the other or the complexity will spiral out of
control. Our decision making may benefit from focusing on achieving one of
them well.
Rich
From: "Dave Cottlehuber" <d...@skunkwerks.at>
To: dev@couchdb.apache.org
Date: 07/04/2021 22:17
Subject: [EXTERNAL] Re: [DISCUSS] API versioning redux
On Fri, 2 Apr 2021, at 21:07, Ilya Khlopotov wrote:
> Nice list of questions. Couple more from me:
>
> # global vs per endpoint?
>
> If we decide for API per endpoint we could different mechanisms to get
> list of supported versions:
> {
> "couchdb": "Welcome",
> "uuid": "85fb71bf700c17267fef77535820e371",
> "vendor": {
> "name": "The Apache Software Foundation",
> "APIs": {
> "/{db}/{docid}": ["4", "55", "95"]
> },
> "version": "1.3.1"
> },
> "APIs": {
> "/{db}/{docid}": ["3", "4", "55"]
> },
> "version": "1.3.1"
> }
> ```
Won't all our client ecosystem will need to be updated to accommodate this
versioning / detection? If so, this should be a simple call, where an API
returns its capabilities early on, and can adjust its settings
accordingly.
We already have `GET / {features: "reshard", ...}` and many clients keep
enough state to be able to do a GET /, and make smart decisions from
there. Would that work?
> # return warnings
>
> - there is an expired IETF draft
>
https://tools.ietf.org/id/draft-cedik-http-warning-02.html
which
> proposes a convention how to inject warnings into JSON response
> - there is a standard Warning header
>
https://tools.ietf.org/html/rfc7234#section-5.5.7
> - Warning: 299 api.couchdb.db.doc "Deprecated API: Use v4 instead."
> - vendors could extend it to look like:
> - Warning: 299 api.couchdb.db.doc "Deprecated API: Use v4 instead.
> Old v3 API maintained until 2015-06-02"
The supported API endpoints will be dependent on what people run on their
servers. Rumours of 1.6 and even 1.3 are still out there... we should just
put this in release notes and roll with it.
What do Large Enterprises see around client versioning and deprecations in
other cloud businesses? It can't be much fun.
A+
Dave
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
