HTTP API (REST)

Versioned JSON under /api/v1 (ADR-032).

Source: docs/adr/ADR-032-http-api-rest.md

ADR-032: API HTTP — REST y OpenAPI

Estado

Accepted — ratificado el 2026-11-11.

Contexto

ADR-012 fija principios de contrato y deja el estilo (REST, GraphQL u otro) a un ADR de tecnología. FoodHub ya eligió REST + OpenAPI para el MVP. El único contrato previsto al inicio es el envío de un lead desde el sitio.

Referencia: FoodHub ADR-014 (API standards). No reutiliza el número 014: en este repo ADR-014 es domain events.

Decisión

  1. El estilo de la API de este producto es REST sobre HTTP, con cuerpos JSON.
  2. El contrato versionado es OpenAPI, en el repo, y la implementación Nest no se adelanta al contrato (ADR-012).
  3. Prefijo de versión explícito (/api/v1).
  4. Errores estructurados, identificador de correlación y nombres del glosario (Lead).
  5. El POST de creación de lead es idempotente mediante una clave de idempotencia, para no duplicar solicitudes al reintentar.
  6. GraphQL y gRPC no forman parte del MVP.

Alternativas consideradas

OpciónPor qué no
GraphQLUn recurso principal no justifica otro estilo
tRPC sin OpenAPIAcopla el cliente al monorepo y se aparta del contrato que FoodHub publica
Server Actions como único contratoNo dejan un contrato HTTP revisable para el lead

Consecuencias

  • ADR-012 queda complementado: el estilo ya no está abierto para este producto.
  • El formulario (ADR-022) consume ese contrato; no persiste el lead desde el componente.
  • Detalle de campos, antispam y privacidad entra en el brief del contacto, no en este ADR.

Enmienda de alcance aceptada 2026-11-12

La motivación inicial describía una web corporativa y un único módulo de leads. DOC-001 v2.0 Approved define ahora web pública, portal cliente y ERP interno. Se mantiene la decisión técnica Accepted de este ADR, pero las referencias a alcance, módulos o número de superficies son históricas. La ampliación se documenta en DOC-017 y ADR-034…039 Accepted, ratificados explícitamente el 2026-11-12 (evidencia). La implementación requiere briefs y specs. No se añade app nativa (ADR-023).