Generate typescript client using OpenAPI doc and Codegen

[fflorent]

While making tools to automate things using Grist, we must use the Rest API.

Grist already use an OpenAPI documentation to document its Rest API. The yaml file can be found here: https://github.com/gristlabs/grist-help/blob/18c08cdd31edcbcc2e0978a432dd1ffac9e1eadc/api/grist.yml

Using this file, tools exist to automatically generate API clients:

• openapi-typescript-codegen ;
• swagger-codegen

These clients bring abstraction around the use of API and provide typing.

Using openapi-typescript-codegen

I made a POC using openapi-typescript-codegen which works quite well:

https://github.com/fflorent/poc-grist-codegen

Next?

I tend to think it would be great to publish some client libraries to help developers interact with the Grist API. We saw that's feasible in nodejs+typescript, and probably more languages could be supported.

Is it something that interests you?

[dsagal]

Yes, that's a great idea. We do have some client libraries (node and python), but they are out of date and aren't similar to each other. A better attempt was made at https://github.com/gristlabs/py_grist_api2. But a codegen-based approach that would produce similar APIs in multiple languages, and would be easier to keep up-to-date, seems ideal.

Last we talked about it, we thought that Stripe offers a good example of solid well-documented client-side libraries. For Stripe, @paulfitz found this:

Stripe's approach seems to be an openapi spec at https://github.com/stripe/openapi and then codegen for client libraries (e.g. here's a pair of PRs for node and ruby stripe/stripe-node#1596 stripe/stripe-ruby#1138).

That's similar to what you are suggesting, @fflorent.

[fflorent]

I see! So you would prefer using the swagger-codegen in order to generate to multiple languages and with a consistent API?

[paulfitz]

It would be great to have client libraries for javascript/typescript and python that are fairly easy to keep up to date with our OpenAPI spec file. If something like swagger-codegen, combined with a relatively small amount of handwritten code for each language (that doesn't need touching most of the time as endpoints are added/changed), resulted in a decent quality library, then that would be great. I don't know how hard it would be to set up, and if it is much more work it would be hard to justify (given that are users largely care about just one of two languages).

[fflorent]

Since my last comment, I attempted to use swagger-codegen and openapi-generator.

With swagger-codegen, I faced a bug that I could not explain (it would need more investigation). However openapi-generator works well.

Still I prefer openapi-typescript-codegen as it supports to pass options (to behave like named parameters in python) and a client instance which allows to get a central constructor for all the backend services. Also it's much simpler to generate the code than swagger-codegen or openapi-generator (which needs to use docker or a machine with java).

That being said, it would generate the client for only typescript + javascript, and would require to generate clients for other languages with other tools than openapi-typescript-codegen.

[paulfitz]

@fflorent I think you should consider yourself free to do whatever appeals to you best here, since there's nothing irrevocable or exclusive about to decision.

[almereyda]

As a side note, implementing a GraphQL endpoint #764 could eventually supersede the approach here for some use cases.

In general I agree that it will be good to have a Grist SDK available for common languages and is often expected from no code web services.