ADR-018 - Backend API Consumption
| Status | accepted |
|---|---|
| Date | 2025-04-17 |
| Decision Makers | Dardan Bujupaj (AX), Martin Klapper (AX), Sandro Wyss (AX) |
Context
We have decided to use:
- the OpenAPI spec to describe our backend API in Frontend-Backend Communication
- Tanstack Query to consume it from the front-end in Frontend Technologies
- Typescript in the frontend Frontend Technologies
We want to leverage typescript type-generation libraries to generate a type-safe representation of our Backend API.
Decision
We will use openapi-ts with their packages openapi-fetch and openapi-react-query.
This is because it:
- provides typesafe api-consumption of our backend API
- is highly customizable
- provides easy integration with Transtack Query
- is actively maintained
- reasonably mature in comparison to alternatives
The openapi-react-query libary is a lightweight wrapper around Tanstack query. This also means we remain flexible if we need to re-evaluate front-end state-management.
Consequences
- All API interaction frontend -> backend will use this library
- API changes must be communicated (and/or versioned)
Alternatives
HeyAPI/openapi-ts
this package provides almost identical functionality as the chosen libary and provides a configuration more akin to e.g. graphql-codegen.
Additionally, it provides support for generating Tanstack Query types using a plugin API via config file and would also allow us to remain flexible.
The main drawback of this library is that it is currently still in initial development and the plugin API is in beta. Therefore it is not suitable for this project.