De API goed gebruiken: cache, webhooks en limieten
PremiumEen 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-Schoolidentificeert het betrokken Omniscol-account;X-OS-authbevat 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-Policygeeft de geldende quota aan, bijvoorbeeld60;w=60, 5000;w=86400;RateLimit-Limitgeeft het quotum aan dat hoort bij de limiet die het dichtst bij het bereiken is;RateLimit-Remaininggeeft het aantal aanvragen aan dat voor dit quotum nog beschikbaar is;RateLimit-Resetgeeft 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).