How back-end and front-end developers became friends 🤗

A journey through OpenAPI specifications, co-written with Guillaume Terral

At Pennylane, as we are growing fast, we have more and more front-end focused developers, who should not handle all the magic that happens on the back-end side. We wanted front-end developers to use and trust the API as our customers would do.

Back in February 2021, during the development of our public API, we were searching for a way to efficiently document our endpoints (shout-out to https://readme.com/), so everyone will be autonomous to use it. We were also searching for a way to guarantee that our documentation was up-to-date with our developments.

We started to read about the committee gem which provides some test helpers that we can use in our specs, and middleware to test that our endpoints were actually receiving and sending what was documented. As inputs, this gem use OpenAPI files.

OpenAPI is a specification that defines a standard way to describe HTTP APIs. It is supported by many libraries and tools. Especially, we discovered that these files can be used to automatically generate an SDK front-end client for our front-end app. That is exactly what the package openapi-client-axios is doing. Giving some OpenAPI specifications files, it generates an axios client, correctly typed, that can be used directly by front-end developers to make requests to our API.

But, the more we were using OpenAPI files, the more we encountered some new problems :

• First, using only one OpenAPI file to document the whole API, being more and more developers, merging all at the same time on master, is just impossible: we had to split our big OpenAPI file, using openapi-cli.
• Second, we wanted all the newcomers to start writing and maintaining OpenAPI file, but sending a message on Slack is not enough: we had to write some specs to enforce that all routes are correctly documented in an OpenAPI file, and that all routes documented in OpenAPI file are actually existing in our application. We also added a custom eslint rule to warn front-end developers to use the generated client, instead of calling axios directly to make HTTP calls.

Finally, we also had to patch the jbuilder library (provided natively by rails) to be able to serialize nil values, and have no optional properties in our JSONs.

You can find more details about some other problems we encountered during our journey through OpenAPI specification in the replay of our talk at Paris.rb here.