API versioning: estrategias que no rompen tus clientes
Breaking change sin versionamiento quema confianza. ¿URI, header o parámetro? Contratos, deprecaciones y comunicación.
Guía por tema
Diseño de APIs robustas: principios REST, trade-offs de GraphQL, versionado, autenticación, webhooks e idempotencia en integraciones reales.
3 temas · 11 artículos
Recursos, verbos HTTP, códigos de estado y versionado.
Breaking change sin versionamiento quema confianza. ¿URI, header o parámetro? Contratos, deprecaciones y comunicación.
La mayoría de las APIs trata errores de forma inconsistente. Un patrón bien definido reduce bugs de integración y facilita el debug.
Authorization code con PKCE reemplazó el flujo implícito. El flujo completo, la validación del ID token y el patrón BFF para SPA sin tokens en localStorage.
Un access token de 15 minutos, un refresh token en cookie HttpOnly, una lista de revocación en Redis y validación de claims en cada request. El flujo completo en Node, del login al logout.
Trade-offs y cuándo usar cada uno.
GraphQL elimina el over-fetching y suma complejidad propia. Dónde le gana a REST hoy y dónde se volvió peso muerto.
Tokens, webhooks y llamadas que se pueden repetir con seguridad.
OAuth 2.0 es un protocolo; JWT es un formato de token. Lo que dicen las RFC 7519, 8725 y 9700 sobre validación, revocación y lo que OAuth exige hoy, como PKCE y un redirect URI exacto.
La red interna no es confiable por defecto. mTLS, JWT entre servicios y workload identity en ambientes reales.
El .env commiteado es el leak más común del mundo dev. Cofres, rotación e inyección segura de credenciales.
Los webhooks fallan en silencio: duplicados, fuera de orden, perdidos. Checklist completo para recibir eventos sin perder ninguno.
La inyección y el control de acceso roto lideran el OWASP Top 10. La prueba de dos usuarios, CSP, Argon2 y el checklist que cierra un riesgo real por vez en el CI.
Token bucket, fixed window y sliding log resuelven problemas distintos. Clave por IP, usuario o API key, headers que el cliente lee y límite por ruta. Código con Redis y express-rate-limit.
REST es más simple y aprovecha la caché HTTP; GraphQL es flexible pero más complejo de operar. Para la mayoría de los casos, empieza con REST.
Para equipos pequeños, generalmente sí. Compensa cuando muchos clientes con necesidades de datos distintas consumen la misma API.
La versión en la URL (/v1/, /v2/) es la forma más clara para quien consume. La versión por header es una alternativa si quieres URLs estables.
En la comunicación interna entre servicios, donde importan el rendimiento y los contratos tipados. Para APIs públicas, prefiere REST: gRPC exige HTTP/2 y payload binario.