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:
- new /_api endpoint which would return list of versions for each endpoint
```
{
"/{db}/{docid}": ["4", "55", "95"]
}
```
- new suffix for each endpoint /{somehing}/_schema which would return JSON
schema or OpenAPI spec for an endpoint including all versions
```
```
- new suffix for each endpoint /{somehing}/_v which would return list of
versions supported on this endpoint
- abuse HEAD http verb to retrieve information about supported versions
- the `/` endpoint could return a list of endpoints and versions they support
(the vendor takes precedence )
```
{
"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"
}
```
- Use dedicated HTTP header and set it in each response X-CouchDB-API: 1, 2, 3,
99
# 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"
- some http frameworks use Deprecation ( expired
https://tools.ietf.org/id/draft-dalal-deprecation-header-01.html) and Sunset
headers https://tools.ietf.org/html/rfc8594
Best regards,
iilyak
On 2021/03/30 22:52:49, San Sato <sans...@inator.biz> wrote:
> Proposed. Mix and match:
>
> - Any expected behaviors dropped or changed from pre-existing API
> versions are available only when API v4 is specified.
> - Any existing behaviors, unchanged in couchdb 4, work the same whether
> API v4 is specified, or not
> - Any new endpoints created in couchdb 4 are available only when API v4
> is specified (=404)
> - - OR -, they respond with an error indicating that v4 is required
> (422?)
> - #include ways-of-indicating-v4
> - start emitting deprecation warnings in v3 api requests
> - e.g. response header: couchdb-warning: start_key is deprecated; use
> startkey instead
> - ...etc...
> - drop v4 support for deprecations (422 error: use of deprecated
> start_key)
> - ? include errors @v3 requests for detected request parameters that are
> clearly v4-targeted (422: feature newAndShiny requires that you
> <indicate-v4-api>)
> - ? be conservative: include v3 deprecation-related behaviors only when
> request-header x-i-want-couchdb-v4: help me
> - other things we want to deprecate @v3 =not support in v4, while the
> window is (?) still open for that
> - plus or minus bike-shedding on header names, message content, 422 vs
> 400 etc.
> - Something else?
>
> Anything about the proposed Replicator changes that would conflict with
> this? I guess the replicator, making a request to a remote server whose
> protocol support is uncertain, would need to start by making a request
> guaranteed to fail on pre-4.0 server - e.g. with /_v4/ url prefix, and from
> there, branch to the appropriate behavior for the remote server's
> capabilities.
>
> San
>
>
> On Tue, Mar 30, 2021 at 2:25 PM Adam Kocoloski <kocol...@apache.org> wrote:
>
> > Thanks for bubbling this thread back up to the top Donat.
> >
> > I think a “cleaner slate” v4 API has a lot going for it, but if we go that
> > route without also supporting the v3 API at the same time we’ll be sunk.
> > Python succeeded in spite of the 2->3 transition, but it was a long and
> > painful road as Joan points out. I’d rather get people on the new version
> > and have them adopt new APIs over time there, rather than make all of that
> > work a gate on adopting 4.0.
> >
> > >>>> If we do want to go with API versioning, can someone help me with a
> > worked example that shows how and when an endpoint gets a new `v_`, how
> > that affects other endpoints, which versions of CouchDB need updating for
> > such a change and when do we get to drop previous versions of the API?
> >
> > That seems like a good set of questions to work through. I wouldn’t think
> > this requires any changes to 3.x and would be something we could introduce
> > going forward in 4.0. As to whether we support N-1, N-2, … versions of the
> > API, I don’t have a strong opinion at the moment. 5.0 is a long ways off :)
> >
> > Cheers, Adam
> >
> > > On Mar 30, 2021, at 4:27 PM, Joan Touzet <woh...@apache.org> wrote:
> > >
> > >
> > >
> > > On 2021-03-30 2:35 p.m., Bessenyei Balázs Donát wrote:
> > >>> It'd be like a Python 2 -> 3 transition
> > >>
> > >> I think the simile is spot on.
> > >> But that shouldn't be a problem, it's more like evolution.
> > >>
> > >>> your user base plummet
> > >>
> > >> Looking at [1] and for lack of a better idea for reference [2], the
> > >> user base issues are not obvious to me.
> > >
> > > It also took them 12 years to get back to that point. Python 3.0 came
> > > out in December 2008. It took until Python 3.5-3.6 or so (3.6 was
> > > released in 2016) before people really started taking Python 3 seriously
> > > for production at scale, I believe. The rest of the people were forced
> > > off of it with the end of support for 2.7 at the beginning of last year.
> > >
> > > If he's back from break, Paul Davis can tell you about all the horrors
> > > of the transition. It was not pretty.
> > >
> > >> Having said that, I'm okay with dropping the idea, I just want to make
> > >> sure it's also considered.
> > >
> > > Not railing against it, just saying, if you expect to succeed, you will
> > > need to do a *LOT* more community work than throwing a release over the
> > > wall and calling it done. It would be wise to at least look into why
> > > Python had such a hard time, and start making concrete plans (and
> > > dedication of people) to avoid a similar trajectory.
> > >
> > > -Joan
> > >
> > >>
> > >> [1]: https://www.jetbrains.com/lp/python-developers-survey-2020/
> > >> [2]: https://www.tiobe.com/tiobe-index//
> > >>
> > >> On Tue, Mar 30, 2021 at 7:20 PM Joan Touzet <woh...@apache.org> wrote:
> > >>>
> > >>>
> > >>>
> > >>> On 30/03/2021 12:57, Bessenyei Balázs Donát wrote:
> > >>>> If we are bumping major anyways, can we just go "clean slate" and
> > >>>> promise replication compatibility only?
> > >>>
> > >>> Basically: watch your user base plummet. It'd be like a Python 2 -> 3
> > >>> transition, or a Perl 5 -> 6 one. It would take years of concerted
> > >>> effort to recover.
> > >>>
> > >>> This is why I'd thought pushing that off to 5.0, with 4.0 being the
> > >>> transitional release, would be best. But I have no strong opinion.
> > >>>
> > >>>> All that while we'd publish a migration guide that explains the
> > >>>> differences and helps users adjust their implementations, but this way
> > >>>> we'd get rid of some potential complexity.
> > >>>>
> > >>>> If we do want to go with API versioning, can someone help me with a
> > >>>> worked example that shows how and when an endpoint gets a new `v_`,
> > >>>> how that affects other endpoints, which versions of CouchDB need
> > >>>> updating for such a change and when do we get to drop previous
> > >>>> versions of the API?
> > >>>
> > >>> I'd like to see this too.
> > >>>
> > >>>> Thank you,
> > >>>> Donat
> > >>>>
> > >>>> On Mon, Mar 29, 2021 at 6:28 PM Joan Touzet <woh...@apache.org>
> > wrote:
> > >>>>>
> > >>>>> On 22/02/2021 20:48, Adam Kocoloski wrote:
> > >>>>>> Hi all,
> > >>>>>>
> > >>>>>> Several times in recent months we’ve had discussions on this list
> > about behavior changes in CouchDB 4.0 that boil down to tradeoffs between
> > >>>>>>
> > >>>>>> a) maintaining compatibility with current CouchDB APIs, and
> > >>>>>> b) capitalizing on the transactional semantics of FoundationDB
> > >>>>>>
> > >>>>>> An example would be the support for large result sets in a view
> > response: do we stitch together multiple transactions to support very large
> > responses, or provide new pagination APIs and guarantee that each response
> > is generated from a single isolated snapshot?
> > >>>>>>
> > >>>>>> I’d like to suggest that we “have our cake and eat it, too” by
> > introducing versioned APIs as previously suggested by Ilya[1]. We’d have a
> > V3 API that strives to maximize compatibility with CouchDB 3.x, and a V4
> > API that still looks and feels like CouchDB, but introduces breaking
> > changes where necessary to provide well-defined transactional semantics. I
> > think this explicit approach to API evolution could make life easier for
> > client library maintainers, and also free us up to improve the API without
> > needing to be quite as careful about in-place backwards compatibility.
> > >>>>>>
> > >>>>>> [1]:
> > https://lists.apache.org/thread.html/rcc742c0fdca0363bb338b54526045720868597ea35ee6842aef174e0%40%3Cdev.couchdb.apache.org%3E
> > >>>>>>
> > >>>>>> What do you think? Cheers, Adam
> > >>>>>
> > >>>>> In general, +1, as long as the concerns raised by Bob are addressed.
> > >>>>> 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."
> > >>>>>
> > >>>>> I've long believed that 4.0 would be a transitional version, and 5.0
> > >>>>> would break things completely... so if 5.0 (or whatever) stops
> > accepting
> > >>>>> "v3" syntax, or "default" changes to "v4", fine by me.
> > >>>>>
> > >>>>> Also it'd be great if this was advertised in the feature strings
> > shown
> > >>>>> in `GET /` in some intelligent way. Maybe an array of API versions
> > >>>>> supported?
> > >>>>>
> > >>>>> -Joan
> >
> >
>
