Rendimiento de API: limitación de velocidad, paginación y procesamiento asíncrono

Su API es tan rápida como su punto final más lento bajo carga máxima. Un único punto final no optimizado que mantiene conexiones de base de datos durante 5 segundos puede agotar su grupo de conexiones y generar fallas en cascada en toda su plataforma. La ingeniería de rendimiento de API se centra en tres pilares: proteger su API de sobrecargas (limitación de velocidad), manejar grandes conjuntos de datos de manera eficiente (paginación) y sacar operaciones costosas del ciclo de solicitudes (procesamiento asíncrono).

Conclusiones clave

• El depósito de tokens y la ventana deslizante son los dos algoritmos de limitación de velocidad que cubren el 95 % de los casos de uso. Elija según si desea tolerancia a ráfagas o aplicación estricta.
• La paginación basada en cursor supera a la paginación desplazada para conjuntos de datos grandes porque evita contar las filas omitidas
• El procesamiento asíncrono con colas de trabajos reduce los tiempos de respuesta de P95 al mover el envío de correo electrónico, la generación de PDF y la entrega de webhooks fuera de la ruta de solicitud.
• La compresión de respuesta con Brotli reduce el tamaño de la carga útil entre un 70% y un 85%, lo que se traduce directamente en una representación más rápida del lado del cliente.

---

Algoritmos de limitación de velocidad

La limitación de velocidad protege su API contra abusos, garantiza una asignación justa de recursos y evita fallas en cascada durante picos de tráfico. El algoritmo que elija determina cómo se manejan las ráfagas y qué tan predecible es el comportamiento limitante para los consumidores.

Cubo de fichas

El algoritmo de depósito de tokens es la opción más práctica para la mayoría de las API. Un cubo contiene fichas hasta una capacidad máxima. Los tokens se agregan a una tasa fija (la tasa de recarga). Cada solicitud consume un token. Si el depósito está vacío, la solicitud se rechaza o se pone en cola.

La ventaja clave del depósito de tokens es la tolerancia al estallido. Si un cliente no ha realizado solicitudes durante un tiempo, su depósito está lleno y puede realizar una ráfaga de solicitudes hasta la capacidad del depósito. Esto coincide con los patrones de uso naturales: un cliente que carga un panel puede realizar 20 solicitudes en rápida sucesión y luego nada durante 30 segundos.

Ejemplo de configuración para una API de comercio electrónico:

• Tamaño del cubo: 100 fichas
• Tasa de recarga: 10 tokens por segundo
• Esto permite ráfagas de hasta 100 solicitudes y al mismo tiempo mantiene 10 solicitudes por segundo a largo plazo.

Mostrador de ventana corrediza

El mostrador de ventana corrediza combina la precisión del registro de ventana corrediza con la eficiencia de memoria de la ventana fija. Mantiene contadores para la ventana actual y anterior, luego calcula un recuento ponderado en función de qué tan lejos de la ventana actual cae la solicitud.

Para una ventana de 60 segundos evaluada en 45 segundos, el recuento efectivo es: (recuento de ventanas anteriores * 0,25) + (recuento de ventanas actuales). Esto elimina el problema de la explosión de límites de las ventanas fijas sin almacenar marcas de tiempo de solicitudes individuales.

Implementación con Redis

Redis es el almacén de respaldo estándar para la limitación de velocidad distribuida porque proporciona operaciones de incremento atómico con TTL. Utilice INCR con EXPIRE para ventanas fijas o conjuntos ordenados con ZADD y ZRANGEBYSCORE para ventanas correderas. Para el depósito de tokens, los scripts de Redis Lua proporcionan operaciones atómicas de verificación y disminución.

Encabezados de limitación de velocidad comunican los límites a los consumidores de API:

• X-RateLimit-Limit -- solicitudes máximas permitidas en la ventana
• X-RateLimit-Remaining -- solicitudes restantes en la ventana actual
• X-RateLimit-Reset -- Marca de tiempo de Unix cuando se reinicia la ventana
• Retry-After - segundos hasta que el cliente debería volver a intentarlo (en 429 respuestas)

---

Estrategias de paginación

Cada punto final de la lista debe estar paginado. Devolver conjuntos de resultados ilimitados desperdicia ancho de banda, sobrecarga la base de datos y corre el riesgo de errores de tiempo de espera a medida que crecen los datos.

Paginación compensada

La paginación compensada utiliza cláusulas SQL LIMIT y OFFSET. El cliente solicita ?page=3&limit=20 y el servidor traduce a OFFSET 40 LIMIT 20.

Ventajas:

• Fácil de implementar y comprender.
• Los clientes pueden saltar a cualquier página directamente
• El recuento total habilita la interfaz de usuario "Página X de Y"

Desventajas:

• El rendimiento se degrada con compensaciones altas: OFFSET 1000000 aún escanea 1.000.000 de filas antes de devolver resultados
• Resultados inconsistentes cuando los datos cambian entre páginas (las filas cambian a medida que se insertan o eliminan nuevos datos)
• La consulta de recuento total (COUNT(*)) puede resultar costosa en tablas grandes

Paginación basada en cursor

La paginación basada en cursor utiliza un cursor opaco (normalmente una clave primaria codificada o una marca de tiempo) para marcar la posición en el conjunto de resultados. El cliente solicita ?cursor=abc123&limit=20 y el servidor usa el cursor como cláusula WHERE: WHERE id > decoded(abc123) LIMIT 20.

Ventajas:

• Rendimiento constante independientemente de la posición en el conjunto de datos: sin escaneo desplazado
• Resultados estables incluso cuando los datos cambian entre páginas
• Ajuste natural para desplazamiento infinito y transmisiones en tiempo real

Desventajas:

• No se puede saltar a páginas arbitrarias (no "Ir a la página 50")
• Más complejo de implementar, especialmente con órdenes de clasificación de varias columnas.
• El recuento total debe proporcionarse por separado si es necesario

Qué paginación utilizar

Formato de respuesta de paginación

Una respuesta de paginación bien diseñada incluye metadatos que los clientes necesitan para navegar:

{
  "data": [],
  "pagination": {
    "total": 15432,
    "limit": 20,
    "hasMore": true,
    "nextCursor": "eyJpZCI6MTAwfQ=="
  }
}

---

Procesamiento asíncrono con colas de trabajos

Los puntos finales de API síncronos deben devolver respuestas dentro de los 200 ms. Cualquier operación que demore más tiempo (enviar correos electrónicos, generar archivos PDF, procesar imágenes, llamar a API externas, ejecutar informes) debe trasladarse a una cola de trabajos en segundo plano.

El patrón de cola de trabajos

1. El punto final API valida la solicitud y crea un registro de trabajo.
2. El trabajo se coloca en una cola (Redis, RabbitMQ, SQS)
3. La API regresa inmediatamente con una respuesta 202 Aceptada y un ID de trabajo.
4. Un proceso de trabajo toma el trabajo y lo ejecuta de forma asincrónica.
5. El cliente consulta el estado del trabajo o recibe una devolución de llamada de webhook al finalizar.

Casos de uso comunes de asíncrono

Envío de correo electrónico: las operaciones SMTP tardan entre 500 ms y 3 s, según el proveedor. Poner en cola los correos electrónicos reduce el tiempo de respuesta de la API y permite la lógica de reintento para fallas transitorias sin bloquear al usuario.

Generación de PDF: la generación de facturas, informes o archivos de exportación consume mucha CPU y mucha memoria. Ejecutarlos en trabajadores dedicados evita la contención de recursos con el manejo de solicitudes de API.

Entrega de webhooks: los webhooks salientes dependen de la disponibilidad del servidor de terceros. Ponga en cola las entregas de webhooks con reintentos de retroceso exponencial (1, 2, 4, 8, hasta 5 minutos) para manejar fallas temporales sin bloquear su sistema.

Importación y exportación de datos: el procesamiento de cargas CSV con 100 000 filas nunca debería ocurrir en un ciclo de solicitud. Acepte la carga, devuelva un ID de trabajo y procese filas en lotes.

Selección de cola

---

Optimización de respuesta

Más allá de la lógica de la aplicación, la respuesta en sí se puede optimizar en cuanto a tamaño y velocidad de entrega.

Compresión

Habilite la compresión de respuesta para reducir el tamaño de la carga útil en la red. Los algoritmos de compresión modernos reducen significativamente las cargas útiles basadas en texto (JSON, HTML, CSS, JavaScript).

Utilice Brotli para recursos estáticos (precomprimidos en el momento de la compilación) y gzip como respaldo para respuestas dinámicas. En NestJS, el middleware de compresión maneja esto automáticamente, pero en producción, deje que Nginx maneje la compresión para descargar la CPU de su servidor de aplicaciones.

Selección de campo

Permita que los consumidores de API soliciten solo los campos que necesitan. GraphQL hace esto de manera inherente, pero las API REST pueden admitir la selección de campos con un parámetro de consulta ?fields=id,name,price. Esto reduce el tamaño de la carga útil y puede optimizar las consultas de la base de datos seleccionando solo las columnas necesarias.

Encabezados de almacenamiento en caché de respuesta

Establezca encabezados Cache-Control apropiados en las respuestas de API. Los puntos finales de la lista pública (productos, categorías) pueden usar Cache-Control: public, max-age=300 para almacenar en caché durante 5 minutos. Los puntos finales autenticados deben usar Cache-Control: private, no-cache para evitar el almacenamiento en caché de CDN y al mismo tiempo permitir el almacenamiento en caché del navegador con revalidación.

Para obtener más información sobre estrategias de almacenamiento en caché, consulte nuestra guía detallada sobre almacenamiento en caché de Redis, CDN y HTTP.

---

Gestión de conexión

Las conexiones HTTP y de bases de datos son recursos finitos que deben administrarse cuidadosamente bajo carga.

Agrupación de conexiones de bases de datos

Un grupo de conexiones mantiene un conjunto de conexiones de bases de datos reutilizables. Sin agrupación, cada solicitud de API abre una nueva conexión de base de datos (entre 50 y 100 ms de sobrecarga) y la cierra después de la respuesta. Con la agrupación, las solicitudes toman prestadas conexiones del grupo y las devuelven cuando terminan.

Fórmula para dimensionar el grupo: conexiones = (core_count * 2) + Effective_spindle_count. Para un servidor de 4 núcleos con almacenamiento SSD, entre 10 y 20 conexiones por instancia de aplicación es un buen punto de partida. Supervise la utilización del grupo: si supera regularmente el 80 %, aumente el tamaño del grupo u optimice la duración de la consulta.

HTTP mantener activo

Habilite HTTP keep-alive para conexiones a servicios ascendentes (bases de datos, Redis, API externas). Esto reutiliza las conexiones TCP en lugar de establecer nuevas por solicitud, lo que elimina el protocolo de enlace TCP y la sobrecarga de negociación TLS (50-200 ms por nueva conexión).

---

Preguntas frecuentes

¿Qué límites de velocidad debo establecer para una API pública?

Comience con límites conservadores y ajústelos según patrones de uso legítimos. Un punto de partida común es 100 solicitudes por minuto para usuarios autenticados y 20 solicitudes por minuto para usuarios anónimos. Supervise las tasas de respuesta 429: si los usuarios legítimos alcanzan los límites con frecuencia, increméntelos. Proporcione límites más altos para los niveles de API premium.

¿Cómo manejo la paginación cuando los datos cambian entre páginas?

La paginación basada en cursor maneja esto de forma natural porque se ancla a una posición específica en los datos ordenados. Con la paginación desplazada, los resultados del documento pueden cambiar entre páginas. Para casos de uso críticos (informes financieros, exportaciones de datos), tome una instantánea de los datos al comienzo de la paginación y pagina sobre la instantánea.

¿Debería usar REST o GraphQL para mejorar el rendimiento?

REST con selección de campos y almacenamiento en caché adecuado es más rápido para puntos finales simples y bien definidos. GraphQL elimina la recuperación excesiva y insuficiente para requisitos de datos complejos, pero agrega una sobrecarga de análisis de consultas y dificulta el almacenamiento en caché HTTP. Utilice REST para API públicas con necesidades de almacenamiento en caché y GraphQL para API internas que cumplan con requisitos complejos de datos de interfaz.

¿Cómo superviso el rendimiento de la API en producción?

Realice un seguimiento de los tiempos de respuesta P50, P95 y P99 por punto final. Establezca alertas cuando P95 infrinja su SLO (normalmente entre 200 y 500 ms). Utilice el seguimiento distribuido para desglosar el tiempo dedicado a la base de datos, la caché, los servicios externos y la lógica de la aplicación. Consulte nuestra guía sobre monitoreo y observabilidad para una configuración detallada.

---

¿Qué sigue?

Comience por auditar los puntos finales de su API en busca de paginación faltante, puntos finales públicos desprotegidos sin limitación de velocidad y operaciones sincrónicas que deberían ser asíncronas. Estos tres cambios normalmente reducen los tiempos de respuesta de P95 entre un 50 y un 70 % y previenen los incidentes de producción más comunes.

Para obtener una perspectiva completa de la ingeniería de rendimiento, consulte nuestra guía fundamental sobre ampliar su plataforma empresarial. Para conocer la capa de base de datos que impulsa su API, lea nuestra guía de optimización de consultas.

ECOSIRE crea API de alto rendimiento para plataformas empresariales en Odoo ERP y arquitecturas personalizadas. Contáctenos para una revisión del rendimiento de la API.

---

Publicado por ECOSIRE: ayuda a las empresas a escalar con soluciones impulsadas por IA en Odoo ERP, Shopify eCommerce y OpenClaw AI.