For the specific case of _changes I think proper handling of the Accept header would make a lot of sense as it is the HTTP way of changing the content-type. As such it is usually much better supported by API tooling than format switching on query parameters.
The eventsource stream is half-way there in that it returns a `content-type: text/event-stream`, but you have to specify `feed=eventsource` - it isn't enabled by passing the `Accept: text/event-stream` header (and you don't get a 406 Not acceptable if you try; you just a get a normal feed response in application/json). The continuous feed is a little more complicated, it isn't valid as `application/json`, but using `text/plain` as a switch is problematic because I think one could reasonably expect to accept other feed types like normal or longpoll feeds with `Accept: text/plain` as an alternative to `application/json`. The output does conform to http://jsonlines.org/ and https://github.com/ndjson/ndjson-spec formats and they have proposed various mime types `application/x-jsonlines`, `application/x-ndjson` etc, but given they are not standardized I don't know how much advantage there is over using say something like `application/x-couch-continuous-json` or similar. The mime type `application/json-seq` is backed by https://tools.ietf.org/html/rfc7464 but would involve adding a record separator character to each line, which may come with a host of problems. Anyway I think with some consideration of a suitable mime-type for continuous it would potentially be possible use accept/content-type to correctly switch between the different feed formats and improve the API without adding new endpoints or necessarily breaking anything. The feed parameter could be left operating as it currently does, but deprecated. From a more general perspective I think that most of the issues I've come across when working with Couch and OpenAPI are related to places where Couch switches type in a schema. An example related to _changes would be the `heartbeat` parameter which can either be a number or a boolean. While it is technically possible to apply multiple types in OpenAPI from a generation perspective this inevitably leads to complications in strongly typed languages. I think it would often be possible to resolve that type of problem in a non-breaking way by continuing to allow both types in the existing parameter, but formally declaring parameters with single types (e.g. heartbeat=number, heartbeatOn=boolean) thus effectively deprecating the use of multiple types within a parameter. Another example, this time unrelated to _changes, would be field sorts in index definitions which can be either a string "field" for default ascending or an object like {"field": "asc"}. When listing indexes IIRC they are returned in the form they were supplied in, but if we could agree for example to continue to accept both forms when defining indexes, but always return the "expanded" object form it would facilitate deserialization in generated tooling. I think that would be considered a breaking change because under some circumstances the response schema changes. I guess the risk is related to how many people rely on being able to parse field sorts from index listings in the same format that they passed them in as. Especially since that as soon as there is a descending field at least some would be in object form. I expect not many people rely on that, but surprise me! Of course there are ways to resolve this without being breaking too, e.g. adding a header to toggle the behaviour or something, but I guess there is a complexity trade-off to be made against the impact. Rich From: Jan Lehnardt <[email protected]> To: [email protected] Date: 22/07/2020 17:23 Subject: [EXTERNAL] Supporting API client generation tools (Was: [DISCUSS] couchdb 4.0 transactional semantics) > On 22. Jul 2020, at 14:48, Bessenyei Balázs Donát <[email protected]> wrote: > > On Tue, 21 Jul 2020 at 18:45, Jan Lehnardt <[email protected]> wrote: >> I’m not sure why a URL parameter vs. a path makes a big difference? >> >> Do you have an example? >> >> Best >> Jan >> — > > Oh, sure! OpenAPI Generator [1] and et al. for example generate Java > methods (like [2] out of spec [3]) per path per verb. > Java's type safety and the way methods are currently generated don't > really provide an easy way to retrieve multiple kinds of responses, so > having them separate would help a lot there. My argument would be that API generation tools that try to abstract over HTTP that aren’t able to really abstract over HTTP aren’t our place to fix ;P But I wouldn’t be averse to adding endpoints that make this easier for these tools. Although I’m sceptical they can deal with our continuous modes anyway. Adding endpoints is not a BC break, and I would not support removing the original versions. We should identify all places that would be problematic before deciding either way. I know a few Cloudant folks have looked at this previously. I also don’t feel too strongly about this, but I’m happy to have a discussion on this. > Donat > > PS. I'm getting self-conscious about discussing this in this thread. > Should I open a new one? Done. Best Jan — > > > [1] https://urldefense.proofpoint.com/v2/url?u=https-3A__openapi-2Dgenerator.tech_&d=DwIFaQ&c=jf_iaSHvJObTbx-siA1ZOg&r=CDCq0vbFWjQXx1sCFm2-iYoMZQ4i0QQj2XmPZmLvZp0&m=WmXheMUT9IgG3YdKmZUSqzi1jkPouvqGjxhZeAgIpME&s=8OeMbyqpeVTzjDG0ka4XOZO3-szC00y7yf24_s-6Z6I&e= > [2] https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_OpenAPITools_openapi-2Dgenerator_blob_c49d8fd_samples_client_petstore_java_okhttp-2Dgson_src_main_java_org_openapitools_client_api_PetApi.java-23L606&d=DwIFaQ&c=jf_iaSHvJObTbx-siA1ZOg&r=CDCq0vbFWjQXx1sCFm2-iYoMZQ4i0QQj2XmPZmLvZp0&m=WmXheMUT9IgG3YdKmZUSqzi1jkPouvqGjxhZeAgIpME&s=nWu6rl-v37I01NCfSi0oh6n4F7q3mVI4QiEw-WngXJ4&e= > [3] https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_OpenAPITools_openapi-2Dgenerator_blob_c49d8fd_samples_client_petstore_java_okhttp-2Dgson_api_openapi.yaml-23L208&d=DwIFaQ&c=jf_iaSHvJObTbx-siA1ZOg&r=CDCq0vbFWjQXx1sCFm2-iYoMZQ4i0QQj2XmPZmLvZp0&m=WmXheMUT9IgG3YdKmZUSqzi1jkPouvqGjxhZeAgIpME&s=jk8-4_GL1RYmmeXESCL_Iz_NarhL3XxNUsl5_MySGCU&e= 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
