Bien utiliser l'API : cache, hooks et limites de débit

Premium

Optimiser les appels à l'API Omniscol : utiliser les ETag pour éviter de récupérer des données inchangées, conserver les réponses en cache, recevoir des notifications de modification grâce aux hooks et respecter les limites de débit par adresse IP et par clé d'API.

Une intégration qui interroge Omniscol toutes les minutes pour vérifier si des données ont changé reçoit, la plupart du temps, la même réponse que lors de son précédent appel. Elle consomme inutilement son quota et sollicite le serveur sans obtenir d'information nouvelle.

Cette page présente les mécanismes permettant d'éviter ces appels superflus et les limites de débit applicables à l'API.

Éviter de récupérer les données inchangées

La plupart des réponses de l'API en lecture comportent un en-tête ETag, qui identifie une version de la réponse. Conservez cet identifiant avec les données reçues et transmettez-le lors de l'appel suivant dans l'en-tête If-None-Match :

curl -i -G "https://votre-etablissement.omniscol.com/api/schedules/lessons/20261102-20261108" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'If-None-Match: W/"os1.…"'

Si les données n'ont pas changé, Omniscol répond 304 Not Modified, sans corps de réponse. Vous pouvez alors réutiliser les données conservées en cache. Dans le cas contraire, vous recevez une réponse 200 OK complète, accompagnée d'un nouvel ETag.

L'ETag est une valeur opaque : conservez-le et renvoyez-le à l'identique, guillemets et préfixe W/ compris, sans chercher à le construire ni à le décoder. Il est propre à la requête qui l'a produit et à l'accès utilisé : ne le réutilisez pas pour une autre URL ni avec un autre jeton.

L'en-tête Cache-Control: private, no-cache précise que la réponse peut être conservée dans un cache privé, mais qu'elle doit être revalidée auprès d'Omniscol avant d'être réutilisée. C'est précisément le rôle de If-None-Match.

Certaines réponses ne comportent pas d'ETag, notamment lorsqu'elles dépendent de la date du jour et peuvent évoluer sans modification des données du compte. Ces réponses doivent être récupérées à nouveau lors de chaque appel.

Après le déploiement d'une nouvelle version d'Omniscol, les ETag sont renouvelés, même si les données n'ont pas changé. Le premier appel reçoit alors une réponse 200, puis les appels suivants peuvent à nouveau bénéficier des réponses 304.

Le 304 réduit également le traitement côté serveur. Dans la plupart des cas, lorsqu'aucune donnée du compte n'a changé depuis le dernier appel, Omniscol peut répondre sans même relire les données concernées, et ce 304 n'est alors pas décompté du quota associé à votre clé d'API. Un 304 obtenu après relecture des données, lui, est décompté comme une réponse ordinaire.

La revalidation régulière reste donc peu coûteuse lorsque les données sont inchangées. Elle demeure toutefois soumise à la limite générale par adresse IP.

Conserver les réponses en cache

Si plusieurs utilisateurs ou plusieurs écrans de votre application consultent les mêmes données, il est inutile d'interroger Omniscol pour chacun d'eux.

Conservez les réponses et leurs ETag dans un cache applicatif sous votre contrôle, par exemple Redis, Memcached ou une table de base de données. Votre application peut alors servir les données depuis ce cache, qui se charge de les revalider auprès d'Omniscol avec If-None-Match, à intervalles réguliers ou lorsqu'un hook signale une modification.

La clé de cache doit tenir compte de l'URL complète, du jeton d'authentification utilisé et, lorsque vous vous en servez, du corps de la requête GET et des en-têtes qui font varier la réponse, comme Accept-Language. Deux jetons disposant de droits différents peuvent donner accès à des données différentes : une réponse obtenue avec l'un ne doit jamais être servie à un utilisateur dont les droits ne permettent pas d'y accéder.

Conservez également le corps de chaque réponse avec son ETag. Sans les données correspondantes, une réponse 304 ne permet pas de reconstituer le résultat attendu.

Ce cache applicatif est distinct d'un cache HTTP partagé : la directive Cache-Control: private interdit à ce dernier de stocker les réponses.

Recevoir des notifications plutôt qu'interroger régulièrement

Au lieu de vérifier périodiquement si des données ont changé, vous pouvez demander à Omniscol de notifier votre application lorsqu'une modification survient.

Ce mécanisme repose sur les hooks, configurables dans l'écran de personnalisation de l'API (voir Personnalisation d'API). Un hook peut surveiller un point d'accès précis ou un évènement regroupant plusieurs modifications, comme la modification d'un emploi du temps.

Invalider le cache à la réception d'un hook

L'utilisation la plus simple consiste à traiter le hook comme un signal d'invalidation.

Lorsqu'une notification arrive, votre application marque les données concernées comme périmées et les revalide auprès d'Omniscol. Il n'est pas nécessaire d'interpréter le contenu de la modification : le hook indique simplement qu'une nouvelle vérification est nécessaire.

Ce fonctionnement se combine naturellement avec le cache décrit précédemment.

Synchroniser les séances par différentiel

Si vous maintenez une copie synchronisée des séances, l'option Avec données de l'évènement de modification d'emploi du temps permet de recevoir un différentiel contenant les séances ajoutées, modifiées et supprimées.

Votre application peut alors appliquer uniquement ces changements, sans récupérer à nouveau l'intégralité de l'emploi du temps.

Assurer la réception des notifications

Omniscol n'effectue qu'une seule tentative d'envoi par hook. Il attend au maximum quatre secondes, ne réessaie pas en cas d'échec et consigne celui-ci dans ses journaux.

Votre serveur doit donc accuser réception rapidement, avec une réponse 200 OK ou 202 Accepted, puis effectuer le traitement nécessaire de manière asynchrone.

Conservez également une revalidation périodique comme mécanisme de rattrapage. Si votre serveur était indisponible lors de l'envoi d'un hook, cette vérification permettra de détecter les modifications manquées. Grâce aux réponses 304, elle reste peu coûteuse lorsque les données sont à jour.

Sécuriser les hooks

Pour vérifier qu'une notification provient bien d'Omniscol, configurez un en-tête HTTP personnalisé contenant un secret connu uniquement de votre application et d'Omniscol. Votre serveur doit refuser les appels qui ne présentent pas la valeur attendue.

Deux en-têtes supplémentaires fournissent des informations sur le contexte de la notification :

  • X-School identifie le compte Omniscol concerné ;
  • X-OS-auth contient le jeton d'authentification de l'utilisateur à l'origine de la modification.

Le jeton transmis dans X-OS-auth est confidentiel. Ne l'enregistrez pas dans vos journaux, ne le transmettez pas à d'autres services et limitez strictement son accès.

Demander uniquement les données nécessaires

Une réponse contenant moins de données est généralement plus rapide à produire, à transférer et à mettre en cache.

Pour les séances, limitez la période demandée et filtrez les résultats sur les entités qui vous intéressent (voir API des séances).

Pour les recherches, le point d'accès search/query propose des filtres, la projection des champs et la pagination (voir Requêtage avancé).

Pour mettre à jour un grand nombre d'éléments de même nature (classes, salles, matières, etc.), privilégiez les points d'accès permettant de transmettre une collection complète en une seule requête, lorsqu'ils sont disponibles dans la documentation OpenAPI, plutôt que de multiplier les appels unitaires.

Respecter les limites de débit

Deux limites de débit s'appliquent aux appels à l'API. Lorsqu'une limite est atteinte, Omniscol répond 429 Too Many Requests, accompagné d'un en-tête Retry-After indiquant le nombre de secondes à attendre avant de renouveler la requête.

Limite par adresse IP

La limite générale est de 300 requêtes par fenêtre de 10 secondes, tous points d'accès de l'API confondus, y compris MCP et les panneaux d'affichage.

Ce seuil est généralement suffisant pour une intégration correctement conçue. Il peut néanmoins être atteint par des boucles d'appels sans temporisation ou par un nombre excessif de requêtes parallèles.

Limite par clé d'API

Les jetons issus d'une même clé d'API partagent deux quotas :

  • 60 requêtes par minute ;
  • 5 000 requêtes par jour.

Les réponses peuvent porter les en-têtes suivants, qui permettent de suivre la consommation :

  • RateLimit-Policy indique les quotas applicables, par exemple 60;w=60, 5000;w=86400 ;
  • RateLimit-Limit indique le quota correspondant à la limite la plus proche d'être atteinte ;
  • RateLimit-Remaining indique le nombre de requêtes encore disponibles pour ce quota ;
  • RateLimit-Reset indique le nombre de secondes avant son renouvellement.

Ces en-têtes sont notamment absents des réponses 304 obtenues sans relecture des données : leur absence ne signifie pas que le quota est épuisé.

Lorsque le quota est épuisé, la réponse 429 indique également le délai d'attente dans son corps, au moyen du champ retry_after.

Les réponses 304 obtenues sans relecture des données ne sont pas décomptées de ces quotas, mais restent soumises à la limite générale par adresse IP.

Si ces limites entravent un usage légitime de l'API, contactez-nous plutôt que de multiplier les clés.

Gérer les erreurs et les nouvelles tentatives

Après une réponse 429

Respectez le délai indiqué par Retry-After avant de renouveler la requête. Réessayer immédiatement est inutile et peut prolonger la situation, notamment si plusieurs processus de votre application effectuent simultanément de nouvelles tentatives.

Après une erreur serveur ou un délai dépassé

Après une erreur 5xx ou un dépassement du délai d'attente, une requête de lecture peut être renouvelée avec un délai croissant entre les tentatives : une seconde, puis deux, puis quatre, par exemple, jusqu'à un nombre maximal d'essais.

Pour une requête d'écriture, la situation est différente : la modification a pu être enregistrée même si la réponse ne vous est jamais parvenue. Vérifiez l'état réel des données avant de renouveler l'opération, afin d'éviter les modifications en double.

Après une réponse 401

Une réponse 401 Unauthorized ne peut généralement pas être résolue par une nouvelle tentative avec le même jeton. Elle peut notamment indiquer que le jeton a expiré, que sa clé d'API a été supprimée ou a expiré, ou que le point d'accès demandé ne fait pas partie de ceux qu'elle autorise.

Vérifiez le jeton et les autorisations associées avant de renouveler l'appel (voir API Omniscol).

Voir aussi