ADR-005-b — API.md Scope: Implemented and Planned Endpoints
ADR-005-b — API.md Scope: Implemented and Planned Endpoints
Sección titulada «ADR-005-b — API.md Scope: Implemented and Planned Endpoints»Accepted
Context
Sección titulada «Context»[[adr-005-api-contract-ssot|ADR-005]] established API.md as the SSOT for HTTP contracts and requires endpoints to be documented before implementation starts. This means API.md inevitably contains fields and computed properties that the backend does not yet return (e.g., coverage_state on PositionListSerializer). A convention is needed to distinguish implementation gaps from spec errors.
Decision
Sección titulada «Decision»If a serializer is missing fields that API.md documents, that is an implementation gap, not a spec error. API.md is the target; the code catches up.
How to tell what is live: check config/urls.py. If the app is routed, the endpoint exists and must match the spec ([[adr-005-api-contract-ssot|ADR-005]] rule 4). Fields absent from the serializer are the backlog — no separate tracking needed.
Consequences
Sección titulada «Consequences»- No
<!-- NOT IMPLEMENTED -->markers inAPI.md. They rot. - Frontend must not consume fields the backend does not yet return. The type system and empty responses are the signal.
- Adding a computed field to a serializer is a routine commit, not a contract change.