erp-construccion/docs/97-adr/ADR-008-api-design.md

ADR-008: API Design RESTful

Estado: Aceptada Fecha: 2025-11-24 Responsable: Architecture-Analyst Proyecto: ERP Construccion

Contexto

APIs deben soportar:

• Operaciones CRUD para todos los modulos
• Integraciones con INFONAVIT
• App movil para asistencias
• Portal de derechohabientes

Decision

API RESTful con:

• Versionado: /api/v1/
• JSON como formato de datos
• Autenticacion JWT
• Rate limiting para integraciones externas

/api/v1/
+-- /auth/              # Autenticacion
+-- /projects/          # Proyectos de construccion
+-- /phases/            # Etapas de fraccionamiento
+-- /lots/              # Lotes/viviendas
+-- /estimates/         # Estimaciones
+-- /infonavit/         # Endpoints INFONAVIT
+-- /portal/            # Portal derechohabientes

Justificacion

Referencia a Odoo

• Odoo usa JSON-RPC, pero REST es mas estandar
• Endpoints similares a Odoo models

Especifico para Construccion

• /portal/* para derechohabientes (read-only)
• /infonavit/* para reportes regulatorios
• /mobile/* para app de asistencias GPS

Consecuencias

Positivas

• API estandar y documentada (OpenAPI)
• Facil integracion con terceros
• Compatible con app movil

Negativas

• No tan flexible como GraphQL
• Mitigacion: Endpoints especificos para reportes complejos

Implementacion

Acciones Requeridas

• Setup Express con versionado
• Documentar con OpenAPI/Swagger
• Implementar rate limiting
• Endpoints especificos para INFONAVIT

Criterios de Aceptacion

• Documentacion OpenAPI completa
• Rate limiting funcional
• Integracion INFONAVIT probada

Referencias

• ERP Generico ADR-008