Usar bien la API: caché, webhooks y límites de frecuencia
PremiumUna integración que consulta Omniscol cada minuto para comprobar si los datos han cambiado recibe, la mayoría de las veces, la misma respuesta que en su llamada anterior. Consume su cuota inútilmente y solicita al servidor sin obtener información nueva.
Esta página presenta los mecanismos que permiten evitar estas llamadas superfluas y los límites de frecuencia aplicables a la API.
Evitar recuperar los datos sin cambios
La mayoría de las respuestas de lectura de la API incluyen un encabezado
ETag, que identifica una versión de la respuesta. Conserve este
identificador junto con los datos recibidos y envíelo en la llamada siguiente
en el encabezado If-None-Match:
curl -i -G "https://su-centro.omniscol.com/api/schedules/lessons/20261102-20261108" \
-H "Authorization: Bearer $TOKEN" \
-H 'If-None-Match: W/"os1.…"'
Si los datos no han cambiado, Omniscol responde 304 Not Modified, sin
cuerpo de respuesta. Entonces puede reutilizar los datos conservados en
caché. En caso contrario, recibe una respuesta 200 OK completa, acompañada
de un nuevo ETag.
El ETag es un valor opaco: consérvelo y devuélvalo tal cual, con las comillas
y el prefijo W/ incluidos, sin intentar construirlo ni decodificarlo. Es
propio de la solicitud que lo produjo y del acceso utilizado: no lo reutilice
para otra URL ni con otro token.
El encabezado Cache-Control: private, no-cache indica que la respuesta
puede conservarse en una caché privada, pero que debe revalidarse ante
Omniscol antes de reutilizarse. Este es precisamente el papel de
If-None-Match.
Algunas respuestas no incluyen ETag, en particular cuando dependen de la fecha del día y pueden cambiar sin que se modifiquen los datos de la cuenta. Estas respuestas deben recuperarse de nuevo en cada llamada.
Tras el despliegue de una nueva versión de Omniscol, los ETag se renuevan,
aunque los datos no hayan cambiado. La primera llamada recibe entonces una
respuesta 200 y las llamadas siguientes pueden volver a beneficiarse de las
respuestas 304.
El 304 también reduce el procesamiento en el servidor. En la mayoría de los
casos, cuando no ha cambiado ningún dato de la cuenta desde la última
llamada, Omniscol puede responder sin siquiera volver a leer los datos
correspondientes, y este 304 no se descuenta de la cuota asociada a su
clave de API. Un 304 obtenido tras volver a leer los datos, en cambio, se
descuenta como una respuesta ordinaria.
La revalidación periódica sigue siendo, por tanto, poco costosa cuando los datos no han cambiado. No obstante, sigue sujeta al límite general por dirección IP.
Conservar las respuestas en caché
Si varios usuarios o varias pantallas de su aplicación consultan los mismos datos, es inútil consultar a Omniscol por cada uno de ellos.
Conserve las respuestas y sus ETag en una caché de aplicación bajo su
control, por ejemplo Redis, Memcached o una tabla de base de datos. Su
aplicación puede entonces servir los datos desde esta caché, que se encarga
de revalidarlos ante Omniscol con If-None-Match, a intervalos regulares o
cuando un webhook señala una modificación.
La clave de caché debe tener en cuenta la URL completa, el token de
autenticación utilizado y, cuando los utilice, el cuerpo de la solicitud
GET y los encabezados que hacen variar la respuesta, como
Accept-Language. Dos tokens con derechos distintos pueden dar acceso
a datos distintos: una respuesta obtenida con uno nunca debe servirse a un
usuario cuyos derechos no permitan acceder a ella.
Conserve también el cuerpo de cada respuesta junto con su ETag. Sin los datos
correspondientes, una respuesta 304 no permite reconstituir el resultado
esperado.
Esta caché de aplicación es distinta de una caché HTTP compartida: la
directiva Cache-Control: private prohíbe a esta última almacenar las
respuestas.
Recibir notificaciones en lugar de consultar periódicamente
En lugar de comprobar periódicamente si los datos han cambiado, puede pedir a Omniscol que notifique a su aplicación cuando se produzca una modificación.
Este mecanismo se basa en los webhooks, configurables en la pantalla de personalización de la API (véase Personalización de API). Un webhook puede vigilar un punto de acceso concreto o un evento que agrupe varias modificaciones, como la modificación de un horario.
Invalidar la caché al recibir un webhook
El uso más sencillo consiste en tratar el webhook como una señal de invalidación.
Cuando llega una notificación, su aplicación marca los datos afectados como obsoletos y los revalida ante Omniscol. No es necesario interpretar el contenido de la modificación: el webhook indica simplemente que es necesaria una nueva comprobación.
Este funcionamiento se combina de forma natural con la caché descrita anteriormente.
Sincronizar las sesiones por diferencial
Si mantiene una copia sincronizada de las sesiones, la opción Con datos del evento de modificación de horario permite recibir un diferencial con las sesiones añadidas, modificadas y suprimidas.
Su aplicación puede entonces aplicar únicamente estos cambios, sin recuperar de nuevo la totalidad del horario.
Asegurar la recepción de las notificaciones
Omniscol realiza un único intento de envío por webhook. Espera como máximo cuatro segundos, no reintenta en caso de fallo y deja constancia de este en sus registros.
Su servidor debe, por tanto, acusar recibo rápidamente, con una respuesta
200 OK o 202 Accepted, y realizar después el procesamiento necesario de
forma asíncrona.
Conserve además una revalidación periódica como mecanismo de recuperación. Si
su servidor no estaba disponible en el momento del envío de un webhook, esta
comprobación permitirá detectar las modificaciones perdidas. Gracias a las
respuestas 304, sigue siendo poco costosa cuando los datos están al día.
Proteger los webhooks
Para verificar que una notificación procede realmente de Omniscol, configure un encabezado HTTP personalizado que contenga un secreto conocido únicamente por su aplicación y por Omniscol. Su servidor debe rechazar las llamadas que no presenten el valor esperado.
Dos encabezados adicionales proporcionan información sobre el contexto de la notificación:
X-Schoolidentifica la cuenta de Omniscol afectada;X-OS-authcontiene el token de autenticación del usuario que originó la modificación.
El token transmitido en X-OS-auth es confidencial. No lo guarde en sus
registros, no lo transmita a otros servicios y limite estrictamente su
acceso.
Pedir únicamente los datos necesarios
Una respuesta con menos datos suele ser más rápida de producir, de transferir y de conservar en caché.
Para las sesiones, limite el periodo solicitado y filtre los resultados por las entidades que le interesen (véase API de las sesiones).
Para las búsquedas, el punto de acceso search/query ofrece filtros,
proyección de campos y paginación (véase
Consultas avanzadas).
Para actualizar un gran número de elementos del mismo tipo (clases, aulas, asignaturas, etc.), dé preferencia a los puntos de acceso que permiten transmitir una colección completa en una sola solicitud, cuando estén disponibles en la documentación OpenAPI, en lugar de multiplicar las llamadas unitarias.
Respetar los límites de frecuencia
A las llamadas a la API se aplican dos límites de frecuencia. Cuando se
alcanza un límite, Omniscol responde 429 Too Many Requests, acompañado de
un encabezado Retry-After que indica el número de segundos que hay que
esperar antes de repetir la solicitud.
Límite por dirección IP
El límite general es de 300 solicitudes por ventana de 10 segundos, sumando todos los puntos de acceso de la API, incluidos MCP y los paneles de visualización.
Este umbral suele bastar para una integración bien diseñada. Sin embargo, puede alcanzarse con bucles de llamadas sin temporización o con un número excesivo de solicitudes en paralelo.
Límite por clave de API
Los tokens procedentes de una misma clave de API comparten dos cuotas:
- 60 solicitudes por minuto;
- 5 000 solicitudes por día.
Las respuestas pueden incluir los siguientes encabezados, que permiten seguir el consumo:
RateLimit-Policyindica las cuotas aplicables, por ejemplo60;w=60, 5000;w=86400;RateLimit-Limitindica la cuota correspondiente al límite más próximo a alcanzarse;RateLimit-Remainingindica el número de solicitudes que aún quedan para esa cuota;RateLimit-Resetindica el número de segundos que faltan para su renovación.
Estos encabezados están ausentes, en particular, en las respuestas 304
obtenidas sin volver a leer los datos: su ausencia no significa que la cuota
esté agotada.
Cuando la cuota se agota, la respuesta 429 indica además el tiempo de
espera en su cuerpo, mediante el campo retry_after.
Las respuestas 304 obtenidas sin volver a leer los datos no se descuentan
de estas cuotas, pero siguen sujetas al límite general por dirección IP.
Si estos límites dificultan un uso legítimo de la API, contáctenos en lugar de multiplicar las claves.
Gestionar los errores y los reintentos
Tras una respuesta 429
Respete el plazo indicado por Retry-After antes de repetir la solicitud.
Reintentar de inmediato es inútil y puede prolongar la situación, sobre todo
si varios procesos de su aplicación realizan nuevos intentos al mismo tiempo.
Tras un error de servidor o un tiempo de espera agotado
Tras un error 5xx o un tiempo de espera agotado, una solicitud de lectura
puede repetirse con un retardo creciente entre los intentos: un segundo,
luego dos, luego cuatro, por ejemplo, hasta un número máximo de intentos.
Para una solicitud de escritura, la situación es distinta: la modificación puede haberse registrado aunque la respuesta nunca le haya llegado. Compruebe el estado real de los datos antes de repetir la operación, para evitar modificaciones duplicadas.
Tras una respuesta 401
Una respuesta 401 Unauthorized normalmente no se resuelve con un nuevo
intento con el mismo token. Puede indicar, en particular, que el token ha
caducado, que su clave de API ha sido eliminada o ha caducado, o que el punto
de acceso solicitado no es uno de los que autoriza.
Verifique el token y los permisos asociados antes de repetir la llamada (véase API de Omniscol).