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 <kocol...@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
