Imaginemos un equipo que desarrolla un portal de clientes. El arquitecto propone definir primero los contratos API para que los desarrolladores web, móviles y los socios externos trabajen de forma independiente. Pero ¿qué ocurre si al principio solo hay una aplicación, un equipo y una base de datos? Diseñar las interfaces pronto puede seguir siendo útil; crear un servicio de red independiente es otra decisión.
API-first consiste en diseñar las interfaces desde el principio y mantener sus acuerdos como parte del producto. Puede facilitar la coordinación, pero exige decisiones sobre compatibilidad, permisos, errores y responsabilidad. La pregunta es quién necesita una interfaz fiable, no si la arquitectura parece moderna.
El contrato precede a la implementación
El equipo define recursos, operaciones, datos, reglas de acceso y comportamiento ante fallos. OpenAPI proporciona una descripción estándar de las API HTTP, independiente del lenguaje, que puede servir para documentación y herramientas. Escribirla no demuestra que la implementación la respete: hacen falta comprobaciones y un responsable.
Los contratos evolucionan conforme se aprende. Cuando otras aplicaciones dependen de ellos, sus cambios necesitan revisión, comunicación y pruebas. Las pruebas de contrato detectan determinadas incompatibilidades, pero no sustituyen las pruebas de extremo a extremo ni las comprobaciones de seguridad.
Cuando varios equipos comparten funciones
En este escenario ficticio, añadamos una aplicación móvil y socios externos que utilizan los mismos datos de clientes y pedidos. No siempre pueden actualizar sus sistemas cada vez que el backend cambia el nombre de un campo. Un contrato estable puede reducir la necesidad de coordinar cada despliegue.
Diseñar primero la interfaz permite discutir datos, permisos y errores antes de que se extiendan supuestos distintos entre los clientes. Esa autonomía requiere mantener el contrato. ¿Quién actualiza la documentación, revisa los cambios incompatibles y decide cuánto tiempo se admiten las versiones anteriores? Una especificación sin responsable es otro documento, no un servicio fiable.
API-first no exige un servicio separado
API-first describe un enfoque de diseño, no una arquitectura de despliegue. Un monolito puede seguirlo y ofrecer endpoints HTTP dentro de la misma aplicación. No requiere microservicios, otra base de datos ni un frontend headless.
Cambiemos ahora una condición: el portal sigue siendo una única aplicación renderizada en el servidor, gestionada por un equipo y sin consumidores independientes. Unos módulos internos bien diseñados pueden cubrir sus necesidades. La comparación trata de justificar una frontera de red, no de cuestionar el valor de las interfaces explícitas.
Una frontera de red introduce timeouts, fallos parciales, controles de acceso y monitorización. Separar los despliegues añade otras responsabilidades. WordPress muestra que el renderizado de páginas y una REST API pueden coexistir: exponer contenido no obliga a sustituir todo el frontend.
Diseña también la petición sin respuesta
Las respuestas correctas solo describen parte del contrato. ¿Qué pasa cuando caduca un token, falta un registro o un proveedor deja de responder? Hay que decidir si el usuario debe reintentarlo y qué peticiones puede repetir el cliente de forma segura.
Un timeout no demuestra que la operación original haya fallado. Repetir sin comprobar una solicitud de pago o de creación de ticket puede generar duplicados. Define errores, reglas de reintento e idempotencia donde sea necesaria. Stripe documenta las claves de idempotencia como ejemplo concreto; su comportamiento y plazo de conservación dependen del proveedor, no son una garantía universal.
El contrato cubre así el comportamiento esperado, además de los campos JSON. Tanto desarrolladores como responsables de operación necesitan esos acuerdos durante un incidente.
Las versiones comprometen con los consumidores
GitHub utiliza versiones fechadas de su REST API y documenta cambios incompatibles como eliminar campos de respuesta, hacer obligatorios parámetros antes opcionales o cambiar los requisitos de acceso. Los consumidores disponen así de un marco explícito de migración.
Es un ejemplo, no un modelo obligatorio. Cada equipo necesita una política de compatibilidad adecuada a sus consumidores. Las incorporaciones suelen ser menos disruptivas que cambiar comportamientos existentes, pero su efecto también depende de cómo los clientes interpretan el contrato.
¿Qué pruebas justifican la inversión?
Empieza por las dependencias reales: consumidores independientes, responsable del contrato, comprobaciones de cambios y gestión de fallos. Compara la frontera de red propuesta con un módulo interno y documenta cuándo debería revisarse la decisión.
| Pregunta | Qué conviene demostrar |
|---|---|
| ¿Hay consumidores independientes? | Un contrato compartido reduce la coordinación entre despliegues. |
| ¿Cómo se gestionan los cambios incompatibles? | Existen un responsable, una política de compatibilidad y una migración verificable. |
| ¿Están definidos los fallos? | Timeouts, accesos denegados, reintentos y duplicados tienen un comportamiento previsto. |
| ¿Puede el equipo operar la API? | Seguridad, monitorización, documentación y responsabilidad de incidentes están cubiertas. |
| ¿Bastaría un módulo interno? | La interfaz de red aporta un valor identificable frente a esa alternativa. |
La misma disciplina puede aplicarse dentro de una aplicación pequeña sin convertir cada módulo en un servicio. Consulta también el dossier de arquitectura web.
Una buena API no se mide por sus endpoints
API-first aporta valor cuando los contratos explícitos permiten trabajar de forma previsible. Las fronteras de red innecesarias y los contratos sin responsable generan costes; el enfoque no los exige. Formaliza los acuerdos imprescindibles y elige el despliegue más sencillo que los sostenga.
Fuentes
- OpenAPI Specification v3.2.1
- GitHub API Versions
- GitHub Breaking Changes
- WordPress REST API Handbook
- Stripe — Idempotent requests
Contacta con nosotros
Cuéntanos cómo podemos ayudarte; responderemos en un plazo de dos días laborables.
