couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Davis <paul.joseph.da...@gmail.com>
Subject Re: API versioning
Date Tue, 28 Apr 2020 00:17:06 GMT
I didn’t read that hard. If memory serves its supposed to be something like
application/json;couchdb._v2 which shouldn’t require registration.
Regardless, being wrong three ways instead of four is fine by me (HIBP
wrong to be clear).

On Mon, Apr 27, 2020 at 5:44 PM Robert Samuel Newson <rnewson@apache.org>
wrote:

> As a general direction, I like it, but the specific example of
> accept/content doesn't sit right with me.
>
> application/couchdb needs registering, which is a faff, and isn't
> appropriate imo as we have many different formats of request and response,
> which a content-type ought to capture. From the post I linked, it's the
> ".v2+json" bit that matters. We could sink a lot of time into declaring
> content types for the all_docs response, the changes response, etc, or do
> something like like Accept: application/json; couch_version=2, or simply
> omit this option and just have the path option, the query parameter option
> and the custom header option.
>
> B.
>
> > On 27 Apr 2020, at 22:34, Paul Davis <paul.joseph.davis@gmail.com>
> wrote:
> >
> > Overall this looks quite good to me. The only thing I'd say is that we
> > should set our version much earlier so we can eventually rely on this
> > for selecting an entirely independent implementation. Though that's
> > not very pressing as once we have the concept embedded we can extend
> > it as needed.
> >
> > For this approach the only thing that concerns me is the way
> > versioning is applied to individual URL handlers. I'd rather see
> > something where we can say "replace these things with newer versions,
> > fall back to v1 for the defaults". Though I couldn't figure out a very
> > clean way to do that. The only thing I came up with was to have a
> > chttpd_handlers_v2.erl service that's called and then
> > chttpd_httpd_handlers_v2.erl that instead of defaulting to `no_match`
> > would just forward to `chttpd_httpd_handlers:url_handler(Req)` or w/e
> > it would be. But to be honest, I'm not super fond of that approach.
> >
> > On Mon, Apr 27, 2020 at 2:41 PM Ilya Khlopotov <iilyak@apache.org>
> wrote:
> >>
> >> I've implemented a PoC for versioned API
> https://github.com/apache/couchdb/pull/2832. The code is very ugly but it
> demonstrates how it could work.
> >>
> >> Best regards,
> >> iilyak
> >>
> >> On 2020/04/27 14:55:10, Ilya Khlopotov <iilyak@apache.org> wrote:
> >>> Hello,
> >>>
> >>> The topic of API versioning was brought in the [Streaming API in
> CouchDB 4.0](
> https://lists.apache.org/thread.html/ra8d16937cca332207d772844d2789f932fbc4572443a354391663b9c%40%3Cdev.couchdb.apache.org%3E)
> thread. The tread proposes to add new API endpoints to introduce a response
> structure change. The alternative approach could be to implement proper
> support for different API versions.
> >>>
> >>> It would benefit CouchDB project if we would have support for API
> versioning. Adding new endpoint is easy but it is very hard to deprecate or
> change the old ones. With proper API versioning we can avoid the need to
> rewrite all client applications at the same time.
> >>>
> >>> rnewson mentioned a good blog post about API versioning (
> https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/). The
> main idea of the blog post is. There is no perfect solution it would be the
> best to support all options so the user can choose which one to use.
> >>>
> >>> In that spirit I propose to implement four different ways of
> specifying the API version (per endpoint):
> >>>
> >>> - Path based -  `/_v{version_number}/{db}/_all_docs`
> >>> - Query parameter based  - `/{db}/_all_docs?_v={version_number}`
> >>> - Accept / Content-Type headers in the form of `application/couchdb;
> _v={version_number},application/json`
> >>> - Custom header - X-Couch-API: v2
> >>>
> >>> The server would include response version in two places:
> >>> - Custom header - `X-Couch-API: v2`
> >>> - `Content-type: application/couchdb;
> _v={version_number},application/json`
> >>>
> >>> Implementation wise it would go as follows:
> >>> 1) we teach chttpd how to extract version (we set version to `1` if it
> is not specified)
> >>> 2) we change arity of chttpd_handlers:url_handler/2 to pass API version
> >>> 3) we would update functions in chttpd_httpd_handlers.erl to match on
> API version
> >>>  ```
> >>>  url_handler(<<"_all_dbs">>, 1)        -> fun
> chttpd_misc:handle_all_dbs_req/1;
> >>>  url_handler(<<"_all_dbs">>, 2)        -> fun
> chttpd_misc_v2:handle_all_dbs_req/1;
> >>>  ...
> >>>  db_handler(<<"_design">>, 1)       -> fun
> chttpd_db:handle_design_req/2;
> >>>  db_handler(<<"_design">>, 2)       -> fun
> chttpd_db_v2:handle_design_req/2;
> >>>  ...
> >>>  design_handler(<<"_view">>, 1)    -> fun
> chttpd_view:handle_view_req/3;
> >>>  design_handler(<<"_view">>, 2)    -> fun
> chttpd_view_v2:handle_view_req/3;
> >>>  ```
> >>> 4) Modify chttpd:send_response to set response version (pass
> additional argument)
> >>>
> >>> I don't expect the implementation to exceed 20 lines of code (not
> counting changes in arity of functions in chttpd_httpd_handlers).
> >>>
> >>> Best regards,
> >>> iilyak
> >>>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message