ADR-005 — API.md as the Single Source of Truth for HTTP Contracts

ADR-005 — API.md as the Single Source of Truth for HTTP Contracts

Status

Accepted

Context

Coveris is a decoupled SaaS: Angular 21 CSR on the frontend, Django 5.2 DRF on the backend. Both sides must agree on endpoint paths, HTTP methods, request/response shapes, status codes, and pagination before any implementation begins. A shared HTTP contract is the single point of coordination between the two systems.

Two naive alternatives were considered:

• DRF auto-schema (drf-spectacular / Swagger) — generated from implementation. Means the backend is the source of truth, but the frontend has no input and no visibility until the backend ships.
• No contract / ad-hoc — each side defines endpoints as needed. Leads to naming inconsistencies, undocumented assumptions, and breakage at integration time.

Decision

Two documents share the API governance:

• API.md (repository root) — Pure endpoint contracts. One block per endpoint: method, path, request schema, response schema, field table, status codes. This is the single source of truth for all HTTP communication between Angular and Django DRF.
• [[api-conventions|docs/stack/api-conventions.md]] — General conventions: URL structure, HTTP methods, pagination, naming, auth mechanism, dates, IDs, throttling, CSRF. Read-once reference material that applies to every endpoint.

API.md references docs/stack/api-conventions.md in its header. The conventions document references API.md as the source of truth for individual endpoints.

Rules:

1. Every new endpoint is defined in API.md before implementation starts — on either side.
2. Angular consumes only what API.md specifies. No endpoint is called unless it is documented there.
3. Django implements only what API.md specifies. No endpoint is exposed unless it is documented there.
4. If API.md and the implementation disagree, API.md wins. The implementation is fixed, not the contract.
5. DRF’s own schema generation (browsable API, docstrings) is not a substitute. It documents implementation detail; API.md documents agreed intent.

Sub-decisions

• [[adr-005-a-contract-testing-pipeline|ADR-005-a]] — Contract Testing Pipeline. Documents how API.md is machine-parsed to generate coverage guards that enforce a 1:1 mapping between documented endpoints and contract tests.
• [[adr-005-b-api-md-scope-implemented-and-planned|ADR-005-b]] — API.md Scope. Clarifies that fields documented in API.md but absent from serializers are implementation gaps, not spec errors. No <!-- NOT IMPLEMENTED --> markers.

Consequences

• Endpoint naming, versioning (/api/v1/), pagination shape, and error format are decided once in docs/stack/api-conventions.md and never re-decided per endpoint.
• Any agent (human or AI) building a new feature must read API.md first and update it before writing any view or service.
• Breaking changes to the contract require updating API.md and are visible in git diff before any code changes.
• DRF auto-schema tools remain available for developer convenience but carry no authoritative weight.
• Adding a new ### METHOD /path/ line to API.md immediately causes the contract coverage guard ([[adr-005-a-contract-testing-pipeline|ADR-005-a]]) to fail until a matching test exists.