Supporting API client generation tools (Was: [DISCUSS] couchdb 4.0 transactional semantics)

[Jan Lehnardt <ja...@apache.org>]

> On 22. Jul 2020, at 14:48, Bessenyei Balázs Donát <be...@apache.org> wrote:
> 
> On Tue, 21 Jul 2020 at 18:45, Jan Lehnardt <ja...@apache.org> 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://openapi-generator.tech/
> [2] https://github.com/OpenAPITools/openapi-generator/blob/c49d8fd/samples/client/petstore/java/okhttp-gson/src/main/java/org/openapitools/client/api/PetApi.java#L606
> [3] https://github.com/OpenAPITools/openapi-generator/blob/c49d8fd/samples/client/petstore/java/okhttp-gson/api/openapi.yaml#L208

Re: Supporting API client generation tools (Was: [DISCUSS] couchdb 4.0 transactional semantics)

[Richard Ellis <RI...@uk.ibm.com>]

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 <ja...@apache.org>
To:     dev@couchdb.apache.org
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 <be...@apache.org> 
wrote:
> 
> On Tue, 21 Jul 2020 at 18:45, Jan Lehnardt <ja...@apache.org> 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