Una API empresarial no es solamente un endpoint: es un contrato operativo, técnico y de seguridad.
Contratos antes que controladores
El diseño debe comenzar por las operaciones que el negocio necesita exponer, los datos mínimos requeridos y las reglas de autorización aplicables.
Los DTO, códigos de respuesta y políticas de versionado forman parte del contrato y deben mantenerse estables para los consumidores autorizados.
- DTO explícitos
- Versionado
- Idempotencia
- Validación de entrada
Seguridad y trazabilidad
La autenticación no sustituye a la autorización. Cada operación debe validar quién solicita la acción, sobre qué recurso y bajo qué alcance.
La bitácora debe permitir reconstruir solicitudes relevantes sin registrar secretos ni datos innecesarios.
- JWT u otro esquema aprobado
- Autorización por alcance
- Rate limiting
- Correlation ID
Evolución controlada
Una API mantenible separa transporte, lógica de aplicación, acceso a datos e integración externa. Esa separación facilita pruebas, cambios de proveedor y nuevas aplicaciones cliente.