ADR-012 — API Contracts

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-012-api-contracts.md

ADR-012: API Contracts

Estado

Accepted — enmendado 2026-08-23 (estilo REST)

Contexto

Hace falta rigor de contrato para que agentes y humanos no improvisen interfaces, pero la semilla no fija REST, GraphQL ni gRPC.

Decisión

Principios obligatorios:

  1. Documentar el estilo elegido en un ADR de tecnología cuando se decida (REST / GraphQL / gRPC / otro).
  2. Contrato primero (spec versionada en el repo) alineada a implementación.
  3. Versionado explícito de la API pública.
  4. Nombres alineados al glosario de dominio.
  5. Convenciones uniformes de listados (paginación/filtros), errores estructurados, correlación de requests e idempotencia en operaciones críticas.

Amendment 2026-08-23 — estilo REST (Accepted)

Cierra el punto 1 para IVPrior, alineado a IVPrior:

  • Estilo: REST JSON sobre HTTP.
  • Prefijo público: /api/v1.
  • Contrato versionado en el repo (packages/api-contract/openapi.yaml cuando exista scaffolding).
  • Recursos nombrados con el glosario: /organizations, /customers, /invoices, /threads, /promises, /disputes, /tasks.
  • GraphQL / gRPC: no en V1.

OpenAPI y controllers se generan en el scaffolding (post-fundación), no antes.

Consecuencias

  • Spec Kit / OpenSpec pueden hablar de capacidades sin acoplar a un stack HTTP.
  • El primer ADR de API del producto debe cerrar estilo + convenciones concretas.

Ver DOC-010 §3.