Hoe Omniscol werkt — één API, één bron van waarheid

Een paar dingen over de manier waarop Omniscol gebouwd is, zijn het waard om te weten voordat u ermee koppelt — ze verklaren waarom de API zo volledig is, hoe de interface zich aan elke gebruiker aanpast, en één punt over privacy om in gedachten te houden.

Eén toepassing op één API

Omniscol draait als één webtoepassing in uw browser. Elk scherm, elke knop en elke tabel wordt getekend door de publieke API van Omniscol aan te roepen — dezelfde API die u zelf kunt aanroepen, gedocumenteerd in de interactieve API-referentie van Omniscol, de pagina Ontwikkelaars (omniscol.com/nl/developers). Er is geen verborgen, “echte” API achter de API waarmee u koppelt: wat de interface gebruikt, is wat u krijgt. Een paar handelingen gaan de andere kant op — aangeboden voor integratie, maar niet gebruikt door de toepassing zelf: bijvoorbeeld de API-endpoints voor geavanceerd zoeken en entiteitsresolutie (bedoeld voor een AI-agent via MCP), of de endpoints waarmee een extern systeem Omniscol van gegevens kan voorzien (een ETL die een externe database synchroon houdt).

operationId — één sleutel, één bron van waarheid

Elke handeling is een combinatie van methode + URL (bijvoorbeeld GET /api/schedules/lessons/{datesrange}), en elke handeling draagt een vaste identificatie: het operationId (hier os_schedules_dates_get). De naam is gestructureerd: os (Omniscol), dan de module (schedules), dan waarop de handeling betrekking heeft (dates — soms meerdere segmenten verbonden door koppeltekens), en altijd de HTTP-methode als laatste (get, post, put, delete). Die ene sleutel gebruikt Omniscol overal — om de handeling op de pagina Ontwikkelaars te benoemen, om de bijbehorende tool voor MCP te bouwen, en om ernaar te verwijzen vanuit een API-aanpassing of vanuit deze help. Eén keer gedefinieerd, houdt hij alle onderdelen synchroon: de documentatie, de tools en de interface kunnen niet uit elkaar lopen, want ze lezen allemaal dezelfde definitie.

De interface volgt uw rechten

Een grafisch element met een actie — een knop, een tabblad, een menu-item — verschijnt alleen wanneer de handeling die eraan ten grondslag ligt voor u toegankelijk is. Dat hangt af van uw rol en van uw aangepaste rollen (zie Gebruikers en rollen), van uw abonnement en van uw opties (zie Abonnementen en opties van Omniscol). Wijzig een van die punten en de interface stelt zich opnieuw samen: elementen, en zelfs hele modules, verschijnen of verdwijnen navenant.

Hetzelfde principe geldt ook buiten uw persoonlijke rechten. De ICT-afdeling kan bepaalde handelingen uitschakelen met een API-aanpassing, waarna de bijbehorende elementen uit de interface verdwijnen (zie API-aanpassingen). Datzelfde gebeurt wanneer gegevens door een externe synchronisatie worden bijgehouden: het lokaal aanmaken en wijzigen ervan kan worden uitgeschakeld, en de knoppen daarvoor maken dan plaats voor de synchronisatie (zie Synchronisatie met externe systemen).

Daarom heeft Omniscol geen apart portaal voor leerlingen of docenten. Er is één toepassing; iedereen ziet de interface afgestemd op zijn eigen rechten — een leerling, een docent, een beheerder en de houder van een aangepaste rol krijgen precies de handelingen waarop zij recht hebben, en niets anders.

De interface is gemak, niet het slot

Omdat de interface door uw rechten wordt aangestuurd, ligt de verleiding voor de hand om een verborgen knop als een beveiligingsgrens te zien. Dat is het niet. Elke aanroep wordt op de server opnieuw gecontroleerd aan de hand van uw identiteit en uw rechten; een handeling waarop u geen recht hebt, wordt daar geweigerd, wat de interface ook toont. De interface past zich aan omwille van de duidelijkheid en het gemak; de echte grens wordt op de server afgedwongen, bij elke aanvraag.

Tokens en deellinks, hetzelfde model

Een API-token of een deellink is beperkt tot een reeks handelingen — die u bij het aanmaken toestaat. De server past die beperking bij elke aanroep toe, precies zoals bij een ingelogde gebruiker. Een deellink, een token en een persoon in de interface zijn drie manieren om dezelfde, door rechten gecontroleerde API te bereiken — nooit een achterdeur die eromheen gaat.

Een verbindingsonderbreking overbruggen

Doordat elk scherm de API leest, kan Omniscol de al ontvangen antwoorden ook in uw browser bewaren, zodat een korte netwerkstoring uw raadpleging niet onderbreekt. Die lokale kopie staat in een eigen database (IndexedDB), naast de gewone paginacache van de browser. Het is een leescache: valt de verbinding weg, dan blijft u zien wat u al had geopend. Hij zet uw wijzigingen niet in een wachtrij en speelt ze niet opnieuw af — een wijziging gaat altijd via de server.

Die lokale kopie berust op uw toestemming. De eerste keer op een browser vraagt Omniscol of u die browser vertrouwt; de kopie begint zodra u akkoord bent gegaan. Het menu-item Offlinecache in het gebruikersmenu schakelt haar daarna op elk moment in of wist haar — een vinkje geeft aan dat ze actief is.

Twee dingen om te weten:

• Persoonsgegevens blijven erbuiten. Alleen geslaagde leesbewerkingen worden bewaard; antwoorden die de server als niet-opslaanbaar markeert (sessie- en authenticatiegegevens) komen nooit in de cache, en de software haalt uit wat er wel in de cache komt de contactgegevens van personen weg — e-mail, telefoon, geboortedatum, login, identificatienummer, status van het wachtwoord — en verwijdert de beheerdersaccounts volledig. De lokale kopie bevat de gewone werkgegevens, niet het adresboek met namen.
• Gebruik op een gedeelde computer bij voorkeur een privévenster. Uitloggen wist die lokale kopie niet (en de gewone browsercache evenmin); een privévenster verwijdert ze allebei zodra u het sluit. Dat is de zorgvuldigheid die elke webtoepassing verdient op een machine die u niet zelf beheert.