Servicios de desarrollo de APIs para plataformas

La decisión la determina el perfil del consumidor, no el gusto del ingeniero. Las API públicas y las integraciones de terceros van con REST y OpenAPI 3.1: es el contrato universal, todos los generadores de SDK lo admiten, todos los gateways de API lo hablan y cualquier cliente puede hacer curl. GraphQL cuando hay un frontend de varios equipos (web + iOS + Android) que consulta un grafo de objetos profundo y el problema de obtener datos de menos o de más (under/over-fetching) es real, federado mediante Apollo Federation 2 o Hot Chocolate cuando varios equipos son propietarios de subgrafos distintos. gRPC para la comunicación interna entre servicios cuando los presupuestos de latencia son ajustados (<10 ms p99) y ambos lados son suyos: protobuf aporta contratos tipados, streaming y multiplexación de conexiones. Nunca usamos GraphQL para la comunicación entre servicios ni gRPC para API públicas.

OpenAPI 3.1 (o un archivo proto, o GraphQL SDL) vive en un repositorio de especificaciones versionado, separado de la implementación. La revisión mediante PR de la especificación se hace antes de escribir una línea de código de handler: producto, frontend, móvil y al menos un consumidor externo (si procede) aprueban el contrato. Spectral valida la especificación frente a su guía de estilo (camelCase frente a snake_case, forma del envoltorio de errores, contrato de paginación, etc.). Los cambios de especificación pasan por openapi-diff con una puerta de CI contra cambios incompatibles: una PR que rompe el contrato exige una etiqueta explícita de subida de versión. Los servidores mock (Prism para REST, Mockoon, subgrafos mock para GraphQL) se despliegan automáticamente por rama para que los equipos de frontend no esperen.

REST: versionado en la ruta del URI (/v1, /v2) para las API públicas (lo más claro para terceros) y basado en cabeceras para las internas donde los consumidores están controlados. Nos comprometemos con el soporte N-2: cuando sale v3, v1 entra en una ventana de obsolescencia de 12 meses con cabeceras Sunset y Deprecation (RFC 8594), correos de recordatorio a los titulares de claves de API a los 90, 30 y 7 días, y un changelog público. GraphQL: directivas @deprecated a nivel de campo con motivo e indicación de migración, y telemetría de uso de Apollo Studio o Hive para confirmar que no hay tráfico antes de retirarlo. gRPC: reglas de evolución de protobuf aplicadas estrictamente (nunca renumerar campos, nunca reutilizar números de campo, solo cambios aditivos sin subir la versión mayor).

OAuth 2.1 + OIDC para la autenticación de cara al usuario (Auth0, WorkOS, Clerk o su propio Keycloak/Ory Hydra cuando se requiere autoalojamiento). mTLS + SPIFFE/SPIRE para la comunicación entre servicios. Claves de API con firma HMAC para las integraciones de socios, JWT con RS256 o EdDSA (nunca HS256 con un secreto compartido en 2026, y nunca RSA por debajo de 2048 bits). La elección del gateway depende del stack: Kong o Tyk para autoalojado, AWS API Gateway / Azure APIM / Apigee para gestionado en la nube, Cloudflare Workers + Hyperdrive para edge-first. Limitación de peticiones en el gateway (ventana deslizante o GCRA, nunca ventana fija ingenua), con techos por clave, por IP y globales. WAF por delante siempre.

OpenTelemetry desde el primer día: trazas, métricas y logs con convenciones semánticas coherentes, exportados a su backend (Datadog, Honeycomb, Grafana Tempo + Mimir + Loki o Elastic). Cada petición lleva un ID de traza visible en las respuestas de error para que soporte pueda obtener la traza completa con un clic. SLO definidos por endpoint (latencia p95/p99, tasa de errores, disponibilidad), presupuestos de error seguidos en Grafana y alertas de burn-rate que avisan a la guardia antes de incumplir el SLO. Paneles de métricas RED (Rate, Errors, Duration) generados automáticamente a partir de la especificación OpenAPI. Monitorización sintética con k6 cloud o Checkly sobre los caminos críticos cada minuto desde US-East y EU-West.

El trabajo de API es de alcance cerrado y escalonado por complejidad, todo incluido y presupuestado en USD. Un puente o una integración única parte de $1,800; una API contract-first con lógica de negocio real, desde $4,100; una API conectada a varios sistemas externos, desde $5,800; una API de plataforma completa (REST más GraphQL federado o gRPC, SDK en varios lenguajes, versionado N-2, SLO por endpoint), desde $10,400. La cifra exacta depende del número de protocolos y endpoints, del número de integraciones, de la complejidad del gateway y de la autenticación, de la profundidad del versionado y del cumplimiento del dominio (PSD2, HL7 FHIR, ISO 20022). Usted ve el presupuesto desglosado tras una evaluación gratuita del alcance y lo aprueba antes de escribir una sola línea de código. La generación de SDK para lenguajes adicionales (TS, Python, Go, Java, C#, Swift, Kotlin) está incluida mediante openapi-generator o stainless.com; sin recargo por intermediación, sin sobrecostes por herramientas, y los costes de la nube, del gateway y de API de terceros corren por sus propias cuentas.

El aislamiento de tenants es una cuestión de diseño de primer nivel, no un añadido posterior. Evaluamos tres modelos al comienzo de cada proyecto de API de SaaS. Modelo pool (un solo esquema, columna tenant_id en cada fila): el más barato de operar, adecuado para SaaS de pymes con cientos de tenants, se apoya en seguridad a nivel de fila (RLS de PostgreSQL o control en la capa de aplicación; nunca solo una cláusula WHERE que un desarrollador podría olvidar). Modelo silo (un esquema por tenant o una base de datos por tenant): el aislamiento más fuerte, necesario cuando los clientes empresariales lo exigen por contrato o cuando los marcos regulatorios (sanidad, datos financieros) exigen una separación demostrable; el coste operativo crece con el número de tenants. Modelo bridge: cómputo compartido y almacenamiento aislado por tenant, un camino intermedio para el SaaS del mercado medio donde el pool es demasiado arriesgado pero el silo completo es demasiado caro. En la capa del gateway aplicamos límites de peticiones y cuotas por tenant con independencia de la autenticación, de modo que un único tenant que dispare el uso no pueda degradar a sus vecinos. La entrega de webhooks incluye firma HMAC por tenant para que sus clientes puedan verificar los eventos sin compartir un secreto entre tenants.

Un gateway de API se sitúa en el límite norte-sur: es el punto de entrada único del tráfico externo y gestiona la autenticación, la limitación de peticiones, el WAF, el enrutamiento y los aspectos de cara al desarrollador, como las claves de API y los planes de uso. Un service mesh gestiona el tráfico este-oeste: comunicación cifrada entre servicios dentro de su clúster, TLS mutuo, circuit breaking, reintentos y observabilidad entre microservicios. Necesita un gateway cuando tiene consumidores externos (integraciones de terceros, su propia app móvil, socios). Necesita un mesh cuando tiene tantos microservicios que no puede confiar en que todos los equipos implementen correctamente en el código de la aplicación mTLS, la lógica de reintentos y los contratos de tiempo de espera. En la mayoría de los proyectos de API empezamos con un gateway (Kong, Tyk o AWS/Azure gestionado) e introducimos un mesh (Istio o Linkerd) solo cuando el número de microservicios supera el umbral en el que la configuración por servicio se vuelve inmanejable, normalmente entre 8 y 12 servicios con equipos distintos responsables de cada uno.

Los SDK se generan a partir de la misma especificación con la que valida el servidor: la especificación es la única fuente de verdad, no un documento que va por detrás de la implementación. El pipeline de generación se ejecuta en CI en cada fusión de la especificación: openapi-generator o stainless.com regenera los clientes tipados para TS, Python, Go, Java, C#, Swift y Kotlin, ejecuta el conjunto de pruebas del SDK generado contra un servidor mock (Prism para REST, subgrafos mock para GraphQL), sube la versión parche o menor de semver y publica automáticamente en npm/PyPI/Maven/NuGet/Packagist. Los cambios incompatibles se bloquean a nivel de especificación con openapi-diff antes de llegar a la generación: una PR que introduce un cambio incompatible requiere una etiqueta explícita de subida de versión mayor, que activa una vía de obsolescencia paralela en lugar de una ruptura silenciosa. Así, el SDK de TypeScript y el de Python de su cliente están siempre a la par con la superficie viva de la API, sin traspasos manuales entre los responsables del backend y de los SDK.

Sí. El trabajo sobre una API heredada empieza con una auditoría del contrato: reconstruimos la especificación a partir de la API en producción (mediante captura de tráfico o el código existente), identificamos endpoints sin documentar, envoltorios de errores incoherentes, brechas de autenticación (secretos compartidos en el código, JWT con HS256 y claves simétricas, ausencia de caducidad de tokens) y deuda de versionado (v1 sin plan de obsolescencia, cambios incompatibles publicados sin subir versión). El resultado es un backlog de remediación priorizado, dividido en crítico para la seguridad (se corrige primero, a menudo en días), estabilidad (limitación de peticiones, contratos de reintento, políticas de tiempo de espera) y experiencia del desarrollador (generación de SDK, documentación de referencia, servidor mock). Podemos operar y mejorar la API en paralelo: no exigimos una reescritura completa antes de hacernos cargo, y le diremos con honestidad si una reescritura es la mejor respuesta a largo plazo frente a una remediación incremental.