# Making an API contract the single source of truth

> Making an API contract the single source of truth, and deriving clients, types and validation from it automatically rather than copying them by hand, is a practice I apply as soon as a project has a well-defined API.

- Source canonique : [https://allaux.fr/en/expertises/generation-de-code-depuis-openapi](https://allaux.fr/en/expertises/generation-de-code-depuis-openapi)
- Langue : EN
- Dernière mise à jour : 2026-09-30

## The typical need

On a project with an API consumed by several clients — a frontend, a mobile app, an external partner — the description of the exchange contract often ends up copied in several places: in the backend code, in the frontend code, in a separate document. These copies drift apart almost inevitably over time: a field renamed on the backend without the frontend being updated at the same time, documentation that becomes wrong without anyone noticing.

## How I approach this kind of work

The OpenAPI specification precisely describes an API's routes, parameters, and request and response formats, in a structured format that tools can read. Rather than writing it after the fact purely for documentation purposes, I treat it as the project's source of truth: backend code can be generated or validated from it, and, more importantly, client code (types, call functions, validation) is generated automatically for each consumer, with no manual copying.

This approach shifts a category of errors from runtime in production to compile time or generation time: a field renamed in the specification immediately breaks client code generation, with an explicit, localised error, rather than a bug discovered by a user weeks later. Getting set up initially requires the discipline of updating the specification with every API change, which is more a change of habit than a technical difficulty.

## Factors that affect the estimate

- **Existing API or one still to design** — Documenting an API already in place requires a different reconstruction effort than designing a specification as the API is being created.
- **Number of consumers of the API** — The benefit of automatic generation grows with the number of different clients that need to stay in sync with the contract.
- **Complexity of the data types** — Nested data structures, or ones with many validation cases, require a more detailed specification to write and maintain.
- **Integration into the development pipeline** — Automating generation on every specification change, rather than occasional manual generation, requires extra initial setup work in the project's tooling.

## Questions to ask before starting

> How many different consumers use or will use this API? Is there already informal documentation to formalise, or does everything need designing from scratch? Who will be responsible for keeping the specification up to date over time?

## FAQ

### Does this approach apply to an API already in production?

Yes, an existing API can be documented retroactively as an OpenAPI specification, then gradually moved over to code generation from that specification.

### Do I need to change language or framework to adopt this practice?

No, generation tools exist for most common languages and frameworks; adoption doesn't require questioning the technical stack already in place.

### What happens if the specification isn't kept up to date?

The benefit gradually disappears, which is why it's worth integrating generation into the usual development pipeline, so updating becomes a natural step rather than a task that's easily forgotten.