APIs bien diseñadas: contratos antes que código
Diseñar una API es escribir un contrato entre equipos, productos y empresas. El código puede rehacerse; el contrato, una vez publicado e integrado, cambia con costo y negociación. Por eso vale la pena invertir tiempo en el formato antes de invertir tiempo en la implementación.
Empieza por el consumidor, no por la base de datos
Una API que refleja tablas obliga a cada cliente a reconstruir la regla de negocio por su cuenta. Una API que expone operaciones significativas del dominio reduce el acoplamiento y evita que la misma lógica se reimplemente en cinco lugares distintos.
Un ejercicio simple ayuda: escribe primero el ejemplo de llamada y de respuesta que te gustaría leer en la documentación. Si el ejemplo es confuso, el diseño todavía no está listo.
- Nombres estables y previsibles, en el mismo idioma en toda la superficie.
- Errores con código, mensaje legible e identificador de correlación.
- Paginación, ordenamiento y filtros definidos desde la primera versión.
Errores e idempotencia son parte del producto
La red falla, el cliente repite, ocurre un timeout. Las operaciones de escritura necesitan una clave de idempotencia para que una repetición no genere dos cobros o dos pedidos. Ese detalle evita la mayoría de los incidentes de integración.
Las respuestas de error merecen el mismo cuidado que las de éxito: previsibles, documentadas y sin filtrar información interna.
Versionar es planificar el cambio
Agregar un campo es seguro; eliminarlo o cambiar su significado, no. Cuando la ruptura es inevitable, publica una nueva versión, mantén la anterior por un plazo anunciado y ofrece un camino de migración. Una política de deprecación escrita vale más que cualquier promesa verbal.
Documentación viva y límites explícitos
La especificación generada a partir del código, ejemplos ejecutables y un entorno de prueba reducen drásticamente el costo de integración. Los límites de uso, cuotas y reglas de autenticación deben estar en la primera página, no en una nota al pie.
En resumen
Una buena API es aquella que alguien integra sin abrir un ticket: contrato claro, errores previsibles, idempotencia y política de versión publicada.
Casos de uso
Integración con ERP de cliente
Contrato estable, clave por socio y reprocesamiento seguro de eventos duplicados.
Webhook para sistemas externos
Firma verificada, reintento con espera progresiva y registro de cada intento.
Aplicación móvil
Respuestas ligeras, versionado tolerante y compatibilidad con versiones antiguas todavía instaladas.
Errores comunes
- Exponer el modelo de base de datos directamente en la respuesta.
- Devolver éxito con un mensaje de error dentro del cuerpo.
- Romper el contrato sin aviso y sin nueva versión.
- Documentar solo el camino feliz.
Buenas prácticas
- Contrato definido y revisado antes de la implementación.
- Clave de idempotencia en toda operación de escritura relevante.
- Límites de uso y autenticación claros por consumidor.
- Pruebas de contrato ejecutadas en el pipeline.
Libros recomendados
Building Microservices — Sam Newman
Aborda integración, contratos y límites de servicio con enfoque práctico.
Domain-Driven Design — Eric Evans
Fundamenta cómo exponer operaciones del dominio en lugar de estructuras internas.
Release It! — Michael Nygard
Muestra patrones de resiliencia indispensables en integración real.
Para profundizar
Preguntas frecuentes
- ¿REST o GraphQL?
- Depende del consumo. REST tiende a ser más simple de operar y cachear; GraphQL ayuda cuando clientes muy distintos necesitan recortes diferentes de los mismos datos.
- ¿Cuándo crear la versión 2?
- Cuando un cambio rompe clientes existentes. Agregar un campo opcional normalmente no requiere una nueva versión.
- ¿Qué es la idempotencia?
- La garantía de que repetir la misma llamada produce el mismo efecto, evitando duplicidad en caso de fallo de red.
- ¿Cómo documentar sin que se vuelva un trabajo manual eterno?
- Generando la especificación a partir del código y validando ejemplos en el pipeline, para que la documentación no se desalinee de la realidad.
Referencias
- Roy Fielding — disertación que origina el estilo REST
- OpenAPI Specification
- Sam Newman — contratos y acoplamiento entre servicios
Contenido original del equipo de i9 Conecty. Los conceptos clásicos se explican con palabras propias y se acreditan a sus autores.