Desarrollo de API personalizadas: proceso y costes

Por qué el diseño de una API perdura más que el código

Una vez que algo consume tu API, su forma queda efectivamente congelada. Puedes reescribir todo lo que hay detrás; no puedes cambiar el nombre de un campo sin más, porque las versiones antiguas de la app siguen en los teléfonos de la gente durante años.

Esa asimetría es la razón por la que el trabajo con APIs debe ser primero de diseño. Una semana dedicada a acordar el contrato antes de implementarlo ahorra considerablemente más después, porque la alternativa es salir de versiones para corregir decisiones tomadas en una tarde.

El proceso que funciona

1. Inventario de consumidores

¿Quién llama a esta API y qué necesitan realmente? Un frontend web, una app móvil, una integración con un socio y un panel interno tienen requisitos genuinamente distintos. Los clientes móviles se preocupan por el tamaño de la carga útil y los viajes de ida y vuelta de una manera que un cliente web en banda ancha no lo hace.

2. Contrato primero

Escribe la especificación —OpenAPI para REST, un esquema para GraphQL— y acórdalo antes de implementar. Esto produce dos beneficios inmediatos: el trabajo de frontend y backend puede avanzar en paralelo contra un mock, y las discrepancias salen a la luz en una revisión del documento en lugar de en pruebas de integración.

3. Modelado de recursos

Los endpoints deben reflejar el dominio de tu negocio, no las tablas de tu base de datos. Exponer directamente la estructura de las tablas es conveniente al principio y se convierte en una jaula: cada cambio de esquema se convierte en un cambio de API que rompe la compatibilidad.

4. Autenticación y autorización

Decide pronto, porque adaptarlo después es doloroso:

• Claves de API para acceso entre servidores en integraciones con socios
• OAuth 2.0 / OIDC cuando los usuarios otorgan acceso a sus propios datos
• JWT de corta duración con tokens de renovación para apps de primera parte

Y mantén la autorización separada de la autenticación. Saber quién es alguien no te dice qué registros puede ver, y confundir ambas es una fuente común de errores de exposición de datos.

5. Errores, paginación, versiones

Las partes poco glamurosas que determinan si la API es agradable de usar:

• Forma consistente de errores con un código legible por máquina y un mensaje para humanos
• Paginación con cursor en lugar de offset, para que los resultados permanezcan estables mientras los datos cambian
• Versionado desde el primer día — /v1/ no cuesta nada ahora y evita una migración más adelante
• Límites de velocidad con encabezados claros, para que los consumidores puedan retroceder en lugar de ser cortados 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. El almacenamiento en caché HTTP funciona, la depuración es sencilla, todos los desarrolladores ya lo conocen y las herramientas son universales.

GraphQL cuando tienes varios clientes distintos que necesitan diferentes formas de los mismos datos, o cuando el sobrecoste en conexiones móviles es un coste medible. Conlleva una complejidad real —almacenamiento en caché, limitación del coste de consultas, protección contra consultas anidadas profundamente— que debe gestionarse activamente.

Elegir GraphQL para un solo cliente web suele ser complejidad sin retorno. Elegir REST cuando tienes cuatro clientes cada uno obteniendo un subconjunto diferente significa o muchos endpoints o mucha carga útil desperdiciada.

¿Cuánto cuesta realmente en el Reino Unido?

Alcance	Rango típico
API enfocada, unos pocos recursos, autenticación	£6.000 – £15.000
Integración con una API de terceros documentada	£2.500 – £6.000
Integración con sistemas heredados o no documentados	£10.000 – £30.000
Puerta de enlace de API, límites de velocidad, portal para desarrolladores	£8.000 – £20.000

El patrón que merece atención: el coste de integración lo determina el otro sistema, no el tuyo. Una API moderna y documentada es una semana de trabajo. Un sistema heredado no documentado con datos inconsistentes y sin entorno de pruebas puede absorber un mes. Por eso lo planteamos primero como una prueba con límite de tiempo en lugar de cotizar a ciegas —un precio fijo en un sistema desconocido es una apuesta que alguien acaba pagando.

Integración de sistemas heredados

La mayoría de los proyectos reales no son de nueva creación. Implican algo antiguo que, no obstante, mantiene el negocio en funcionamiento.

Si tiene una API, espere que sea inconsistente, lenta y que limite la tasa de uso de formas no documentadas. Construya de manera defensiva: reintentos con retroceso exponencial, disyuntores de circuito y una cola para que una dependencia lenta no arrastre su aplicación consigo.

Si no tiene API, las opciones en orden descendente de solidez son: un intercambio de archivos programado (CSV o XML sobre SFTP), una integración de base de datos de solo lectura cuando el proveedor lo permite, o —en casos limitados— automatización de procesos robóticos que controle la interfaz. Esta última es francamente frágil y se rompe cada vez que el proveedor cambia una pantalla. La implementaremos si es la única vía, siendo claros sobre lo que está aceptando.

Siempre añada una capa de anticorrupción. Traduzca el modelo del sistema heredado al suyo en el límite, en lugar de permitir que sus peculiaridades se propaguen por su base de código. Esa única decisión determina si reemplazar el sistema heredado más adelante será un proyecto o una pesadilla.

Errores comunes

1. Exponer tablas de bases de datos como puntos finales — acopla su API a su esquema de forma permanente
2. Sin versión — el primer cambio que rompa todo se convierte en una emergencia
3. Autenticación añadida después — inevitablemente implica reescribir cada punto final
4. Sin limitación de tasa — un consumidor mal escrito deja el servicio fuera de servicio para todos
5. Errores inconsistentes — cada consumidor escribe un manejo personalizado por punto final
6. Documentación escrita al final — por lo que queda mal escrita o directamente no se hace

Qué se considera un buen resultado al entregar

• 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
• Limitación de tasa con encabezados informativos
• Registro estructurado y seguimiento de errores
• Documentación con ejemplos prácticos
• Un entorno de pruebas monitorizado al que los consumidores puedan desarrollar

Próximos pasos

Si está planeando una integración y el sistema en el otro extremo es una incógnita, el primer paso sensato es una breve prueba pagada 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ó.