DR: Use automated API client generator to create language specific libraries

This is a record in the Decision Records on Solutions Adopted.

Issue

None

Problem statement

Writing REST API adapter code in the client side takes frontend developer effort and is error-prone.

1. It results in wrapper code at best, usually in something like a service folder, where each API endpoint has a corresponding wrapper file whose purpose is to serialize data, make the CRUD API calls, and then to deserialize the response into an object that the client code can work with.
   1. The worst case is that API calls are mixed into application code, which makes it very difficult to maintain.
2. When the server API changes, developers working on the clients consuming the API will need to make the corresponding modifications to update their service files. This wastes efforts depending on the number of projects using the API (x3 for us: VRMS, Website, CivicTechJobs).
   1. If the API is deployed, it can result in runtime problems where the frontend didn't realize the backend was updated and didn't make the necessary changes.

Potential solution

Use the openapi-generator to generate the API client library for use by any frontend code. We're targeting javascript frontends so we would generate typescript code.

• It's essentially a wrapper that hides the actual network requests and deserializing the data into objects. To the client code, it would feel like calling a library function and getting back an object ready to use.
• See this for exactly what to do.
• We can set up a gh action to auto-generate this library on commit to main or to a release branch.

Pros

• It's easy to do. We're already partially there by using drf-spectacular to generate our API documentation for CRUD operations, which is a requirement for using the generator.
• It's automatic. There can be a github workflow to generate the library when the backend API changes.
• It saves frontend developers from having to do it manually. This approach moves the work that needs to be done manually in each frontend's codebase into something that comes from the single backend. The more frontend clients consume the API, the stronger the reason to use the generator.
• It eliminates an entire class of bugs for typed frontends. For frontends using a typed language like typescript (CivicTechJobs), an API client library that's generated in typescript will stop type mismatch bugs from happening without even connecting to the backend, saving developer from having to debug it later. VS Code will also provide better guidance when there's already type information available.
• Here's a post with arguments for using the generator.

Cons

• It makes developers too comfortable with the higher level abstraction. This approach abstracts away the REST API calls, which is good, but if beginning developers only know this easier way, they may have a harder time working with raw calls to API endpoints in the future. They will have to learn or re-learn how to do it the harder way.

Feasibility determination

This solution is technically feasible and easy to implement. We're trying to decide if its impact is something we can live with, versus not doing it.

Decision

In the context of frontend projects, facing the extra developer work of writing and maintaining an API wrapper that can be easily and automatically generated, we decided for implementing the API generator, to achieve the effect of allowing the developers to work on real frontend issues, accepting the downside of the developers becoming out of practice with writing API wrapper code, because frontend developers should be able to focus on the frontend code and not be bogged down by work they can avoid.