Por qué el diseño de la API supera al código
Una vez que algo consume tu API, su forma queda efectivamente congelada. Puedes reescribir todo lo que hay detrás; no puedes renombrar un campo a la ligera si una aplicación móvil en producción depende de él, porque las versiones antiguas de las apps siguen en los teléfonos de la gente durante años.
Esa asimetría es la razón por la que el trabajo de API debe ser primero en diseño. Una semana acordando el contrato antes de la implementación ahorra considerablemente más tiempo después, porque la alternativa es salir de decisiones tomadas en una tarde mediante versionado.
El proceso que funciona
1. Inventario de consumidores
¿Quién consume esto y qué necesita realmente? Una interfaz web, una app móvil, una integración con un socio y un panel interno tienen requisitos genuina y diferentes. Los clientes móviles se preocupan por el tamaño de la carga y las rondas de viajes de una manera que un cliente web en banda ancha no.
2. Contrato primero
Escribe la especificación — OpenAPI para REST, un esquema para GraphQL — y acuerdala antes de implementarla. Esto produce dos beneficios inmediatos: el trabajo del front-end y el back-end pueden avanzar en paralelo contra un mock, y los desacuerdos surgen en una revisión de documento en lugar de en pruebas de integración.
3. Modelado de recursos
Los endpoints deben reflejar tu dominio de negocio, no tus tablas de base de datos. Exponer la estructura de la tabla directamente es conveniente al principio y se convierte en una jaula: cada cambio en el esquema se convierte en un cambio de ruptura en la API.
4. Autenticación y autorización
Decide temprano, porque retroceder es doloroso:
- Claves de API para acceso de servidor a servidor entre socios
- OAuth 2.0 / OIDC cuando los usuarios otorgan acceso a sus propios datos
- JWT de corta duración con tokens de refresco para apps de primera parte
Y mantén la autorización distinta de la autenticación. Saber quién es alguien no te dice qué registros puede ver, y confundir las dos es una fuente común de errores de exposición de datos.
5. Errores, paginación, versionado
Las partes menos glamurosas que determinan si la API es agradable de construir:
- Formato de error consistente con un código legible por máquina y un mensaje para humanos
- Paginación por cursor en lugar de offset, para que los resultados permanezcan estables mientras los datos cambian
- Versionado desde el día uno —
/v1/no cuesta nada ahora y ahorra una migración después - Límite de tasa con encabezados claros, para que los consumidores puedan retroceder en lugar de ser desconectados en silencio
6. Documentación como entregable
Referencia generada más ejemplos prácticos, incluyendo cómo autenticarse y qué significan los errores comunes. Si un desarrollador competente no puede realizar una llamada exitosa en veinte minutos de leerla, la documentación no está terminada.
REST o GraphQL
REST para la gran mayoría de proyectos. La caché HTTP funciona, el depuración es sencillo, todos los desarrolladores ya lo conocen y las herramientas son universales.
GraphQL cuando tienes varios clientes diferentes que necesitan formas distintas de los mismos datos, o cuando el sobrecarga en conexiones móviles es un costo medible. Trae una complejidad real — caché, límite de costo de consulta, protección contra consultas profundamente anidadas — que debe ser gestionada activamente.
Elegir GraphQL para un solo cliente web suele ser complejidad sin retorno. Elegir REST cuando tienes cuatro clientes que cada uno extrae un subconjunto diferente significa o muchas endpoints o mucho payload desperdiciado.
¿Cuánto cuesta realmente en el Reino Unido
| Alcance | Rango típico |
|---|---|
| API enfocada, pocos recursos, autenticación | £2,400 – £6,000 |
| Integración con una API de terceros documentada | £1,000 – £2,400 |
| Integración con sistemas legacy o no documentados | £4,000 – £12,000 |
| Gateway de API, límite de tasa, portal para desarrolladores | £3,200 – £8,000 |
El patrón que vale la pena notar: el costo de integración está impulsado por el otro sistema, no por el tuyo. Una API moderna y documentada es cuestión de una semana. Un sistema legado no documentado con datos inconsistentes y sin entorno de prueba puede absorber un mes. Por eso los abordamos primero como un estudio exploratorio con tiempo limitado en lugar de cotizar a ciegas — un precio fijo en un sistema desconocido es una suposición que alguien terminará pagando.
Integración de sistemas legacy
La mayoría de los proyectos reales no son greenfield. Involucran algo antiguo que, sin embargo, sigue haciendo funcionar el negocio.
Si tiene una API, espere que sea inconsistente, lenta y que limite la tasa de solicitudes de formas no documentadas. Desarrolle de manera defensiva: implementaciones con retardo exponencial, interruptores de circuito y una cola para que una dependencia lenta no derribe su aplicación.
Si no tiene API, las opciones, ordenadas de mayor a menor robustez, son un intercambio de archivos programado (CSV o XML a través de SFTP), una integración de base de datos de solo lectura cuando el proveedor lo permita, o — en casos muy limitados — automatización robótica que maneje la interfaz. La última opción es genuina y frágil, y se rompe cada vez que el proveedor modifica una pantalla. La implementaremos si es la única vía, pero dejando claro lo que se está aceptando.
Siempre añada una capa anticorrupción. Traduzca el modelo del sistema legado al suyo en el límite, en lugar de permitir que sus peculiaridades se extiendan por toda la base de código. Esa única decisión determina si reemplazar el sistema legado más adelante será un proyecto o una pesadilla.
Errores comunes
- Exponer tablas de base de datos como endpoints — acopla tu API al esquema de forma permanente
- Sin versionado — el primer cambio que rompe la compatibilidad se convierte en una emergencia
- Autenticación añadida después — significa invariablemente una reescritura de cada endpoint
- Sin límite de tasa — un consumidor mal escrito puede dejar fuera de servicio el servicio para todos
- Errores inconsistentes — cada consumidor escribe un manejo personalizado por endpoint
- Documentación escrita al final — por lo que suele estar mal hecha o no existir
En qué consiste un buen resultado al entregarse
- Especificación OpenAPI acordada antes de comenzar la implementación
- Pruebas automatizadas que cubran el contrato documentado
- Autenticación y autorización como preocupaciones separadas y probadas
- Límite de tasa con encabezados informativos
- Registro estructurado y seguimiento de errores
- Documentación con ejemplos prácticos
- Un entorno de staging monitorizado donde los consumidores puedan desarrollar
Próximos pasos
Si está planeando una integración y el sistema del otro lado es una incógnita, el primer paso sensato es un spike pagado y breve para determinar qué es realmente posible. Suele costar una fracción del proyecto y, en ocasiones, revela que la integración que le cotizaron no puede construirse como se describió.
Preguntas frecuentes
Una API enfocada con unos pocos recursos y autenticación suele costar entre £2,400 y £6,000. Integrarse con un sistema legado complicado o de terceros suele costar entre £4,000 y £12,000, porque la mayor parte del costo recae en el otro sistema y no en el tuyo. Una integración bien documentada con un tercero puede costar entre £1,000 y £2,400.
REST para la mayoría de los casos: más sencillo de almacenar en caché, más sencillo de depurar y todos los desarrolladores ya lo entienden. GraphQL justifica su complejidad cuando varios clientes diferentes necesitan distintas formas de los mismos datos o cuando el ancho de banda móvil hace que la sobrecarga de datos sea realmente costosa. Elegir GraphQL para un único cliente web suele añadir complejidad sin retorno.
Entre cuatro y ocho semanas para una API enfocada, incluyendo documentación y pruebas. Las integraciones dependen casi por completo de la calidad del sistema en el otro extremo: una API moderna bien documentada puede llevar una semana, un sistema heredado sin documentación puede llevar considerablemente más tiempo, y esa incertidumbre debe tratarse como un estudio previo en lugar de adivinarla.
Suele haber opciones: intercambio de archivos programado, integración a nivel de base de datos (si está permitido) o, en casos limitados, automatización de procesos robóticos. Todas son menos robustas que una API adecuada, y le diríamos claramente los compromisos en lugar de presentar un enfoque frágil como equivalente.
- API
- integration
- REST
- GraphQL
- architecture