De API goed gebruiken: cache, webhooks en limieten

Premium

De aanroepen van de Omniscol-API optimaliseren: ETags gebruiken om ongewijzigde gegevens niet opnieuw op te halen, antwoorden in de cache bewaren, via webhooks bericht krijgen van wijzigingen en de limieten per IP-adres en per API-sleutel respecteren.

Een integratie die Omniscol elke minuut bevraagt om te controleren of gegevens zijn gewijzigd, krijgt meestal hetzelfde antwoord als bij haar vorige aanroep. Zij verbruikt zonder reden haar quotum en belast de server zonder nieuwe informatie te verkrijgen.

Deze pagina beschrijft de mechanismen om deze overbodige aanroepen te vermijden en de limieten die voor de API gelden.

Ongewijzigde gegevens niet opnieuw ophalen

Bij de meeste leesantwoorden van de API hoort een ETag-header, die een versie van het antwoord identificeert. Bewaar deze identificatie samen met de ontvangen gegevens en stuur haar bij de volgende aanroep mee in de header If-None-Match:

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

Als de gegevens niet zijn gewijzigd, antwoordt Omniscol met 304 Not Modified, zonder berichttekst. U kunt dan de in de cache bewaarde gegevens hergebruiken. In het andere geval ontvangt u een volledig 200 OK-antwoord met een nieuwe ETag.

De ETag is een ondoorzichtige waarde: bewaar haar en stuur haar ongewijzigd terug, met de aanhalingstekens en het voorvoegsel W/, zonder te proberen haar samen te stellen of te ontcijferen. Zij geldt alleen voor de aanvraag die haar heeft voortgebracht en voor de gebruikte toegang: gebruik haar niet opnieuw voor een andere URL of met een ander token.

De header Cache-Control: private, no-cache geeft aan dat het antwoord in een privécache mag worden bewaard, maar dat het bij Omniscol opnieuw gevalideerd moet worden voordat het wordt hergebruikt. Dat is precies de taak van If-None-Match.

Sommige antwoorden bevatten geen ETag, met name wanneer ze afhangen van de datum van vandaag en kunnen veranderen zonder dat de gegevens van het account zijn gewijzigd. Deze antwoorden moeten bij elke aanroep opnieuw worden opgehaald.

Na de uitrol van een nieuwe versie van Omniscol worden de ETags vernieuwd, ook als de gegevens niet zijn veranderd. De eerste aanroep ontvangt dan een 200-antwoord, waarna de volgende aanroepen weer kunnen profiteren van 304-antwoorden.

Een 304 vermindert ook de verwerking aan de serverzijde. In de meeste gevallen, wanneer er sinds de laatste aanroep geen gegevens van het account zijn gewijzigd, kan Omniscol antwoorden zonder de betrokken gegevens opnieuw te lezen, en wordt deze 304 niet meegeteld in het quotum van uw API-sleutel. Een 304 die na het opnieuw lezen van de gegevens wordt verkregen, wordt daarentegen als een gewoon antwoord meegeteld.

Regelmatige hervalidatie blijft dus goedkoop zolang de gegevens ongewijzigd zijn. Zij valt echter wel onder de algemene limiet per IP-adres.

Antwoorden in de cache bewaren

Als meerdere gebruikers of meerdere schermen van uw toepassing dezelfde gegevens raadplegen, hoeft u Omniscol niet voor elk van hen te bevragen.

Bewaar de antwoorden en hun ETags in een toepassingscache die onder uw beheer staat, bijvoorbeeld Redis, Memcached of een databasetabel. Uw toepassing kan de gegevens dan uit deze cache aanbieden, die ze met If-None-Match bij Omniscol hervalideert, met regelmatige tussenpozen of wanneer een webhook een wijziging meldt.

De cachesleutel moet rekening houden met de volledige URL, het gebruikte authenticatietoken en, wanneer u ze gebruikt, de berichttekst van de GET-aanvraag en de headers die het antwoord laten variëren, zoals Accept-Language. Twee tokens met verschillende rechten kunnen toegang geven tot verschillende gegevens: een antwoord dat met het ene is verkregen, mag nooit worden aangeboden aan een gebruiker wiens rechten geen toegang daartoe geven.

Bewaar ook de berichttekst van elk antwoord samen met zijn ETag. Zonder de bijbehorende gegevens kan een 304-antwoord het verwachte resultaat niet reconstrueren.

Deze toepassingscache verschilt van een gedeelde HTTP-cache: de richtlijn Cache-Control: private verbiedt laatstgenoemde de antwoorden op te slaan.

Meldingen ontvangen in plaats van regelmatig te bevragen

In plaats van periodiek te controleren of gegevens zijn gewijzigd, kunt u Omniscol vragen uw toepassing op de hoogte te stellen wanneer er een wijziging plaatsvindt.

Dit mechanisme berust op webhooks, die u configureert in het aanpassingsscherm van de API (zie API-aanpassingen). Een webhook kan een specifiek eindpunt bewaken of een gebeurtenis die meerdere wijzigingen groepeert, zoals de wijziging van een rooster.

De cache ongeldig maken bij ontvangst van een webhook

Het eenvoudigste gebruik is de webhook als een signaal voor ongeldigmaking te behandelen.

Wanneer er een melding binnenkomt, markeert uw toepassing de betrokken gegevens als verouderd en hervalideert zij ze bij Omniscol. U hoeft de inhoud van de wijziging niet te interpreteren: de webhook geeft alleen aan dat een nieuwe controle nodig is.

Deze werkwijze laat zich vanzelf combineren met de eerder beschreven cache.

De lessen synchroniseren op basis van de verschillen

Als u een gesynchroniseerde kopie van de lessen bijhoudt, laat de optie Met gegevens van de gebeurtenis voor de wijziging van een rooster u een overzicht van de verschillen ontvangen, met de toegevoegde, gewijzigde en verwijderde lessen.

Uw toepassing kan dan uitsluitend deze wijzigingen toepassen, zonder het volledige rooster opnieuw op te halen.

Zorgen dat de meldingen aankomen

Omniscol doet per webhook slechts één verzendpoging. Het wacht maximaal vier seconden, probeert het bij een mislukking niet opnieuw en legt de mislukking vast in zijn logboeken.

Uw server moet dus snel ontvangst bevestigen, met een antwoord 200 OK of 202 Accepted, en de nodige verwerking daarna asynchroon uitvoeren.

Houd ook een periodieke hervalidatie aan als vangnet. Als uw server niet beschikbaar was toen een webhook werd verzonden, kunt u met deze controle de gemiste wijzigingen opsporen. Dankzij de 304-antwoorden blijft zij goedkoop wanneer de gegevens actueel zijn.

De webhooks beveiligen

Om te controleren dat een melding wel degelijk van Omniscol afkomstig is, configureert u een aangepaste HTTP-header met een geheim dat alleen uw toepassing en Omniscol kennen. Uw server moet de aanroepen weigeren die de verwachte waarde niet bevatten.

Twee extra headers geven informatie over de context van de melding:

  • X-School identificeert het betrokken Omniscol-account;
  • X-OS-auth bevat het authenticatietoken van de gebruiker die de wijziging heeft veroorzaakt.

Het token in X-OS-auth is vertrouwelijk. Leg het niet vast in uw logboeken, geef het niet door aan andere diensten en beperk de toegang ertoe strikt.

Alleen de nodige gegevens opvragen

Een antwoord met minder gegevens is doorgaans sneller te produceren, over te dragen en in de cache te bewaren.

Beperk voor de lessen de opgevraagde periode en filter de resultaten op de entiteiten die u interesseren (zie Lessen-API).

Voor zoekopdrachten biedt het eindpunt search/query filters, projectie van velden en paginering (zie Geavanceerde queries).

Om een groot aantal elementen van dezelfde soort (klassen, lokalen, vakken enzovoort) bij te werken, geeft u de voorkeur aan de eindpunten waarmee een volledige verzameling in één aanvraag kan worden verstuurd, wanneer deze in de OpenAPI-documentatie beschikbaar zijn, in plaats van veel afzonderlijke aanroepen te doen.

De limieten respecteren

Op de aanroepen van de API gelden twee limieten. Wanneer een limiet wordt bereikt, antwoordt Omniscol met 429 Too Many Requests, vergezeld van een header Retry-After die het aantal seconden aangeeft dat u moet wachten voordat u de aanvraag opnieuw verstuurt.

Limiet per IP-adres

De algemene limiet is 300 aanvragen per venster van 10 seconden, alle eindpunten van de API samen, inclusief MCP en de informatieschermen.

Deze drempel volstaat doorgaans voor een goed ontworpen integratie. Hij kan echter worden bereikt door aanroeplussen zonder vertraging of door een overmatig aantal parallelle aanvragen.

Limiet per API-sleutel

De tokens die uit dezelfde API-sleutel voortkomen, delen twee quota:

  • 60 aanvragen per minuut;
  • 5 000 aanvragen per dag.

De antwoorden kunnen de volgende headers bevatten, waarmee u het verbruik kunt volgen:

  • RateLimit-Policy geeft de geldende quota aan, bijvoorbeeld 60;w=60, 5000;w=86400;
  • RateLimit-Limit geeft het quotum aan dat hoort bij de limiet die het dichtst bij het bereiken is;
  • RateLimit-Remaining geeft het aantal aanvragen aan dat voor dit quotum nog beschikbaar is;
  • RateLimit-Reset geeft het aantal seconden aan tot het wordt vernieuwd.

Deze headers ontbreken met name in de 304-antwoorden die zonder het opnieuw lezen van de gegevens zijn verkregen: hun afwezigheid betekent niet dat het quotum is uitgeput.

Wanneer het quotum is uitgeput, geeft het 429-antwoord de wachttijd ook aan in zijn berichttekst, in het veld retry_after.

De 304-antwoorden die zonder het opnieuw lezen van de gegevens zijn verkregen, worden niet in deze quota meegeteld, maar vallen wel onder de algemene limiet per IP-adres.

Als deze limieten een legitiem gebruik van de API belemmeren, neem dan contact met ons op in plaats van het aantal sleutels te vermenigvuldigen.

Fouten en nieuwe pogingen afhandelen

Na een 429-antwoord

Respecteer de door Retry-After aangegeven wachttijd voordat u de aanvraag opnieuw verstuurt. Onmiddellijk opnieuw proberen is nutteloos en kan de situatie verlengen, vooral als meerdere processen van uw toepassing gelijktijdig nieuwe pogingen doen.

Na een serverfout of een overschreden time-out

Na een 5xx-fout of een overschreden wachttijd kan een leesaanvraag opnieuw worden verstuurd met een toenemende vertraging tussen de pogingen: bijvoorbeeld een seconde, dan twee, dan vier, tot een maximumaantal pogingen.

Voor een schrijfaanvraag ligt de situatie anders: de wijziging kan zijn opgeslagen, ook al heeft het antwoord u nooit bereikt. Controleer de werkelijke toestand van de gegevens voordat u de bewerking opnieuw uitvoert, om dubbele wijzigingen te voorkomen.

Na een 401-antwoord

Een 401 Unauthorized-antwoord kan doorgaans niet worden opgelost door het opnieuw te proberen met hetzelfde token. Het kan met name aangeven dat het token is verlopen, dat de API-sleutel is verwijderd of verlopen, of dat het gevraagde eindpunt niet tot de eindpunten behoort die de sleutel toestaat.

Controleer het token en de bijbehorende machtigingen voordat u de aanroep opnieuw uitvoert (zie Omniscol-API).

Zie ook