You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Adam Kocoloski <ko...@apache.org> on 2021/02/23 01:48:40 UTC
[DISCUSS] API versioning redux
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
Re: [DISCUSS] API versioning redux
Posted by Nick Vatamaniuc <va...@gmail.com>.
I think that's a good compromise if we want to bring more users along
from 3.x to 4.x.
In respect to existing users I can see there being at least 4
different categories:
1. Users who know about the snapshotting behavior of 1.x-3.x, and
their applications rely on it for correctness.
2. Users who don't know about the snapshotting, and their applications
rely on it for correctness.
3. Users who know about the snapshotting behavior, but their
applications don't rely on it for correctness.
4. Users who don't know about the snapshotting behavior and their
applications don't rely on it for correctness
I worry about 1 and especially 2. Documenting the differences in
behavior there would be crucial. Hopefully after learning about the
feature a bit more, the majority of those users will be able to tell
if it affects their application or not. At the same time, the users in
category 3 and 4 won't feel like they need to do a lot of grunt work
for seemingly no reason, if they want to use 4.x for scalability or
other reasons like not having to deal with spurious conflicts.
Good point that being explicit about versions would allow us to not
worry as much about in-place backward compatibility. I like the idea
of the v4 API getting all kinds of new and interesting features:
transactional PATCH across multiple docs, bulk docs with transactional
guarantees and so on -- it would offer enough of a "carrot" for users
to look forward to and want to use the new API, instead of being
forced by the "stick" of the old API being removed.
As for the warnings and global vs per endpoint, I think global and no
warnings might be a good start? We can always add warnings and
per-endpoint schemas later, but it's harder to remove them once we've
already added them.
-Nick
On Mon, Feb 22, 2021 at 8:48 PM Adam Kocoloski <ko...@apache.org> 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
Re: [DISCUSS] API versioning redux
Posted by Richard Ellis <RI...@uk.ibm.com>.
>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" <dc...@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
Re: [DISCUSS] API versioning redux
Posted by Dave Cottlehuber <dc...@skunkwerks.at>.
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
Re: [DISCUSS] API versioning redux
Posted by Ilya Khlopotov <ii...@apache.org>.
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 <sa...@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 <ko...@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 <wo...@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 <wo...@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 <wo...@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
> >
> >
>
Re: [DISCUSS] API versioning redux
Posted by San Sato <sa...@inator.biz>.
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 <ko...@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 <wo...@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 <wo...@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 <wo...@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
>
>
Re: [DISCUSS] API versioning redux
Posted by Adam Kocoloski <ko...@apache.org>.
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 <wo...@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 <wo...@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 <wo...@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
Re: [DISCUSS] API versioning redux
Posted by Joan Touzet <wo...@apache.org>.
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 <wo...@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 <wo...@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
Re: [DISCUSS] API versioning redux
Posted by Bessenyei Balázs Donát <be...@apache.org>.
> 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.
Having said that, I'm okay with dropping the idea, I just want to make
sure it's also considered.
[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 <wo...@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 <wo...@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
Re: [DISCUSS] API versioning redux
Posted by Joan Touzet <wo...@apache.org>.
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 <wo...@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
Re: [DISCUSS] API versioning redux
Posted by Bessenyei Balázs Donát <be...@apache.org>.
If we are bumping major anyways, can we just go "clean slate" and
promise replication compatibility only?
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?
Thank you,
Donat
On Mon, Mar 29, 2021 at 6:28 PM Joan Touzet <wo...@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
Re: [DISCUSS] API versioning redux
Posted by Joan Touzet <wo...@apache.org>.
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
Re: [DISCUSS] API versioning redux
Posted by Ilya Khlopotov <ii...@apache.org>.
Thank you Adam for bringing back API versioning discussion.
I think we should adopt API versioning. This would allow us to get a number of benefits:
1. It would allow clients to choose appropriate API based on explicit API version support returned response from /
2. It would allow us to run two versions of APIs on the same cluster to simplify replication of data and smoother the upgrade of client libraries
3. It would allow us to write version adapters (adapter pattern from GoF) which would convert very old API on the fly to the newest supported API. This would allow us to cleanup codebase and move ancient craft into version adapter.
4. We would be able to introduce incompatible changes into replicator protocol and adopt modern approaches to set reconciliation (IBLT or PBS based for example)
5. We would be able to drop bug compatibility approach to API evolution and introduce strict validation of input parameters
6. We can introduce openAPI specification and code generate:
- input validation rules
- some test cases
- http endpoints code
- authorization rules (https://github.com/apache/couchdb/blob/main/src/chttpd/src/chttpd_auth_request.erl#L41:L107)
- handler_info rules https://github.com/apache/couchdb/blob/main/src/chttpd/src/chttpd_httpd_handlers.erl#L62:L495
7. Once we achieve 6) we can easily change the template used for code generation to adopt different http server framework.
Best regards,
iilyak
On 2021/02/23 01:48:40, Adam Kocoloski <ko...@apache.org> 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