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
- El estilo de la API de este producto es REST sobre HTTP, con cuerpos JSON.
- El contrato versionado es OpenAPI, en el repo, y la implementación Nest no se adelanta al contrato (ADR-012).
- Prefijo de versión explícito (
/api/v1). - Errores estructurados, identificador de correlación y nombres del glosario (
Lead). - El
POSTde creación de lead es idempotente mediante una clave de idempotencia, para no duplicar solicitudes al reintentar. - GraphQL y gRPC no forman parte del MVP.
Alternativas consideradas
| Opción | Por qué no |
|---|---|
| GraphQL | Un recurso principal no justifica otro estilo |
| tRPC sin OpenAPI | Acopla el cliente al monorepo y se aparta del contrato que FoodHub publica |
| Server Actions como único contrato | No 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).