Qué es el caché de API: cabeceras, capas e invalidación

¿Qué es el caché de API?

El caché de API consiste en guardar una respuesta de la API para que las peticiones idénticas posteriores se respondan desde la copia almacenada en lugar de repetir el trabajo. La copia puede estar en el cliente, en una CDN, en un API gateway o en tu propia aplicación. Una respuesta en caché es más rápida y alivia el backend, pero puede estar desactualizada, así que toda decisión de caché es un equilibrio entre velocidad y frescura.

Dónde se guardan las respuestas

• Caché del cliente o del navegador. Un caché privado de un solo usuario. Evita por completo el viaje por la red.
• CDN o proxy inverso. Un caché compartido cerca de los usuarios. Consulta redes de distribución de contenido. Solo ayuda con respuestas iguales para muchos usuarios.
• API gateway. Un caché compartido delante de tus servicios, controlado por las reglas del propio gateway.
• Caché de aplicación. Memoria del proceso o un almacén como Redis. A menudo se cachea la consulta costosa o el valor calculado, no toda la respuesta HTTP.
• Caché de base de datos. Búferes y cachés de consultas dentro de la base de datos, casi siempre automáticos.

Las cabeceras HTTP que lo controlan

La RFC 9111 define cómo se comportan las cachés HTTP. Las cabeceras de respuesta principales son:

• Cache-Control: max-age=60: la respuesta se mantiene fresca 60 segundos. s-maxage fija la frescura solo para cachés compartidas.
• Cache-Control: no-cache: la respuesta puede guardarse, pero debe revalidarse con el origen antes de cada reutilización. No significa "no cachear".
• Cache-Control: no-store: ninguna caché, privada o compartida, debe guardar la respuesta.
• Cache-Control: private: solo una caché privada, como la del navegador, puede guardarla. public permite cachés compartidas y solo hace falta cuando la petición llevaba una cabecera Authorization.
• ETag e If-None-Match: el cliente envía el validador guardado y el servidor responde 304 Not Modified sin cuerpo si nada cambió.
• Vary: nombra las cabeceras de la petición que cambian la respuesta, como Accept-Language, para que cada variante se cachee por separado.
• stale-while-revalidate y stale-if-error: extensiones de la RFC 5861 que permiten a una caché servir una copia caducada mientras la renueva, o cuando el origen falla.

Si no indicas ninguna información de frescura, las cachés pueden aplicar frescura heurística, normalmente una fracción del tiempo transcurrido desde Last-Modified. Mejor define Cache-Control de forma explícita. La guía de caché HTTP de MDN trae ejemplos.

Ejemplo

Un endpoint público, GET /api/v1/products, cambia unas pocas veces por hora. Puede responder con Cache-Control: public, max-age=60 y un ETag, de modo que una CDN absorba la mayoría de las lecturas y los clientes revaliden a bajo coste. Un endpoint personalizado, GET /api/v1/me, debería enviar Cache-Control: private, no-cache con un ETag: el navegador puede conservarlo, pero debe consultar antes al servidor, y ninguna caché compartida lo guarda. La clave de caché incluye la URL completa, así que una lista paginada necesita la página o el cursor en la query string; consulta paginación de API.

Estrategias e invalidación

• Cache-aside. La aplicación consulta la caché, carga desde el origen si falla y guarda el resultado. El patrón más simple y habitual.
• Write-through. Las escrituras actualizan la caché y el origen a la vez. Las lecturas son coherentes, las escrituras más lentas.
• Caducidad por TTL. Las entradas expiran. Es sencillo, pero los datos pueden estar desactualizados hasta el TTL tras un cambio.
• Purga al cambiar. Se borran las claves o etiquetas afectadas cuando cambian los datos. Es preciso, pero cada escritor debe saber qué purgar.
• URL versionadas. Poner una versión o un hash de contenido en la URL crea una clave de caché nueva con cada cambio.

La invalidación es donde viven la mayoría de los errores de caché. Nuestra guía sobre la invalidación de caché en las pruebas de rendimiento muestra cómo las cachés obsoletas y frías distorsionan los resultados.

Errores comunes

• Dejar que respuestas personalizadas entren en una caché compartida. Márcalas como private. Una cookie por sí sola no hace privada una respuesta.
• Un Vary ausente o demasiado amplio. Sin él se sirve la variante equivocada. Variar por User-Agent fragmenta tanto la caché que casi nunca acierta.
• Cachear errores. Un 500 guardado con frescura larga sigue fallando para todos. Da a las respuestas de error una frescura corta o nula.
• Cache stampede. Cuando caduca una clave muy usada, muchas peticiones fallan a la vez y golpean el origen. Usa un bloqueo al rellenar, renovación anticipada o stale-while-revalidate.
• Suponer que un POST se cachea. La RFC 9111 permite cachear métodos distintos de GET solo si el método lo permite y define cómo construir la clave, y en la práctica las cachés rara vez guardan respuestas POST. La idempotencia trata de reintentos seguros, no de si algo es cacheable.
• No medir. Sin tasa de aciertos ni carga sobre el origen por endpoint, no se puede ajustar un TTL.

Probar y monitorizar una caché

Prueba el caché de dos maneras. De forma funcional: envía dos veces la misma petición y revisa cabeceras y tiempos; una respuesta en caché debería ser más rápida y llevar las cabeceras de frescura previstas. Bajo carga: ejecuta el endpoint con la caché caliente y con parámetros que la esquiven, y compara los tiempos de respuesta y la carga que llega a tu origen en tus propias métricas. Puedes empezar con una prueba de carga de API gratuita. Tras el lanzamiento, la monitorización de API sigue vigilando: LoadFocus API Monitoring puede comprobar el código de estado, el cuerpo, las cabeceras y el tiempo de respuesta, así que un despliegue que pierda Cache-Control o ralentice un endpoint cacheado queda señalado. Las comprobaciones gratuitas se ejecutan cada 5 minutos. Los límites de tasa también se relacionan con la caché, porque los aciertos servidos desde ella normalmente no llegan al limitador; consulta las causas habituales del rate limiting de API.

Preguntas frecuentes: caché de API

¿Qué debería cachear primero?

Empieza por los endpoints de lectura lentos, muy solicitados, que cambian poco y cuya respuesta es la misma para muchos usuarios. Mide la latencia y el volumen de peticiones por endpoint para decidir.

¿Qué diferencia hay entre no-cache y no-store?

no-cache permite guardar la respuesta pero obliga a revalidarla con el origen antes de cada reutilización. no-store indica a las cachés que no guarden la respuesta en absoluto.

¿Puedo cachear peticiones POST?

Rara vez. Las cachés HTTP guardan sobre todo respuestas a GET. Algunas APIs cachean POST de tipo búsqueda en la capa de aplicación con una clave explícita, pero una CDN o un navegador no lo harán por defecto.

¿Una CDN es lo mismo que el caché de API?

No. Una CDN es un lugar donde se cachea, en el borde. El caché de API abarca todas las capas, del navegador a la base de datos.

¿Cómo cacheo una API GraphQL?

Las consultas suelen viajar en el cuerpo de un POST, así que el caché por URL no se aplica. Las opciones habituales son las consultas persistidas enviadas por GET o cachear a nivel de resolver o de aplicación.

¿Cómo sé si una respuesta vino de la caché?

Compara los tiempos, mira la cabecera Age y cualquier cabecera de estado de caché que añada tu CDN, y comprueba si la petición llega a los logs de tu origen.