Geavanceerde queries — de API filteren, projecteren en pagineren

De drie ingangen in één oogopslag

Alle drie staan ze in de interactieve API-referentie (de pagina /developers), onder de sectie Search, en ze vereisen authenticatie — zie Omniscol-API.

Het filter where (in Mango-/MongoDB-stijl)

/api/search/entity en /api/search/query accepteren allebei een where-clausule: een gestructureerd filter met operatoren in MongoDB-stijl. Een veld komt overeen met ofwel een rechtstreekse waarde (impliciete gelijkheid), ofwel een object met operatoren; meerdere operatoren op hetzelfde veld worden gecombineerd met een impliciete EN. De veldnamen accepteren de puntnotatie om een bovenliggende context te bereiken (bijvoorbeeld sites.name).

Een paar voorbeelden:

{ "capacity": { "$gte": 20, "$lte": 50 } }
{ "level": { "$in": ["vmbo", "havo", "vwo"] } }
{ "name": { "$regex": "^lab" } }
{ "city": { "$like": "s hertogenbosch" } }
{ "$or": [ { "capacity": { "$gte": 50 } }, { "specialisation": "chemistry" } ] }

Projectie, sortering en paginering

Op /api/search/query houden nog vier knoppen het antwoord compact en geordend — wat telt voor een dashboard, en nog meer voor een AI-agent die per token wordt afgerekend:

• project — de lijst met velden die u wilt behouden (puntnotatie toegestaan). Al het overige valt af.
• sort — één veld, asc of desc. Het pseudoveld _count.<veld> sorteert op de lengte van een arrayveld.
• limit en offset — pagineren de resultaten.

Het antwoord bevat ook een meta-blok: hoeveel elementen er vóór het filteren waren, hoeveel er door het filter zijn gekomen, en hoeveel er zijn teruggegeven.

Een volledig voorbeeld

De lokalen met minstens 30 plaatsen zoeken, alleen hun naam en hun capaciteit behouden, van groot naar klein, en de eerste 20 nemen:

curl -X POST "https://uw-school.omniscol.com/api/search/query" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "call": "os_dashboard_classrooms_get",
        "where": { "capacity": { "$gte": 30 } },
        "project": ["name", "capacity"],
        "sort": { "capacity": "desc" },
        "limit": 20
      }'

call is de interne naam van het uit te voeren lees-endpoint (zoals het op de pagina /developers wordt weergegeven), params bevat de parameters die eigen zijn aan dat endpoint, en extract_path wijst zo nodig de array aan die binnen het resultaat gefilterd moet worden — hier weggelaten, wordt die automatisch herkend.

Een vrij lokaal of een vrije docent vinden

De meest voorkomende integratie — een intranet, een reserveringstool of een ETL voeden — is “wie of wat is op dat moment vrij?”. De availability-endpoints beantwoorden dat rechtstreeks: ze geven per entiteit alleen de vrije tijdslots op de gevraagde datums terug, waarbij de lessen, de afwezigheden en de verplichte beschikbaarheid al zijn meegerekend.

De beschikbaarheid vraagt u op twee manieren op:

• Afgebakend — GET /api/schedules/availability/{datesrange}/{entity} (zo nodig /{entityId}) voor één entiteitstype — teachers, classrooms, groups, resources…
• Expliciet filter — GET /api/schedules/availability/{datesrange} met een filter, waarmee u de verzameling inperkt met dezelfde $where als hierboven.

{datesrange} schrijft u als YYYYMMDD, en segmenten gescheiden door komma's vragen losse datums op — ideaal voor “twee bepaalde maandagen”: 20261005,20261012. Elk teruggegeven tijdslot bevat day, start, end en time (in minuten): “minstens 3 uur” wordt aan uw kant dus een test time >= 180.

Een docent die vrij is op een bepaald tijdslot

“Welke docenten zijn vrij op maandag 5 oktober?” — één enkele afgebakende aanroep:

curl -G "https://uw-school.omniscol.com/api/schedules/availability/20261005/teachers" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode "with_entities=true"

De vrije tijdslots komen gegroepeerd terug, eerst per soort en dan per docent — bijvoorbeeld { "availability": { "teachers": { "d.devries": [ { "day": "2026-10-05", "start": "14:00", "end": "17:00", "time": 180 } ] } } } — en uw tool kiest het tijdslot dat het gewenste moment dekt.

Lokalen van een bepaalde omvang, vrij op twee maandagen

Combineer een entiteitsfilter en de beschikbaarheid in één enkele aanroep, met een nuttige deelverzameling van de syntaxis — enkel $where op de capaciteit:

curl -G "https://uw-school.omniscol.com/api/schedules/availability/20261005,20261012" \
  -H "Authorization: Bearer $OMNISCOL_TOKEN" \
  --data-urlencode 'filter={"classrooms":[{"$where":{"capacity":{"$gte":30}}}]}' \
  --data-urlencode "with_entities=true"

Omniscol geeft de vrije tijdslots terug, op beide maandagen, van elk lokaal met minstens 30 plaatsen. Uw ETL houdt vervolgens de lokalen over die op elk van de datums een venster van 3 uur hebben (time >= 180) — het samenstellen over meerdere dagen blijft aan uw kant, wat de regel expliciet en controleerbaar houdt.

Het filter accepteert, per entiteitstype, een eenvoudige lijst met identificaties ({"classrooms":["A101","B204"]}), een jokerteken ({"teachers":"*"}), een eenvoudige veldovereenkomst ({"teachers":[{"email":"…"}]}) of de gestructureerde $where die hier getoond wordt.

De juiste ingang kiezen

• “Waar komt dit woord voor?” → POST /api/search.
• “Met welke entiteit komt deze naam overeen?” → POST /api/search/entity.
• “Geef me de lokalen met meer dan 30 plaatsen, gesorteerd, eerste pagina” → POST /api/search/query.
• “Wie of wat is vrij op dit tijdslot?” → GET /api/schedules/availability/….

Voor een AI-agent

Deze ingangen bestaan voor een groot deel voor AI-agenten. Het zoeken in de volledige tekst en de entiteitsresolutie zetten de formulering van een gebruiker (“docent Jan de Boer”, “klas 4V”) om in precieze identificaties; de query-orkestrator beantwoordt daarna een gefilterde vraag in één enkele aanroep en geeft alleen de gevraagde velden terug — in plaats van meerdere aanroepen en een veel te groot antwoord. Wanneer u een agent aansluit via MCP — een externe AI-agent aansluiten, horen deze tools bij wat hij kan gebruiken.

Aansluiten op een intranet, een ETL of een partnertool

Dezelfde lees-ingangen zijn wat een externe tool dagelijks aanroept. Gangbare vormen:

• Een ophaalactie naar een intranet of een dashboard — uw pagina roept de lees-endpoints aan (beschikbaarheid, het endpoint voor de lessen, de dashboards) met een beperkt API-token, en toont het resultaat. Aan de kant van Omniscol hoeft u niets te installeren.
• Een nachtelijke ETL — een geplande taak haalt op wat ze nodig heeft (de lessen over een datumvenster, de uren van een docent, de bezetting van de lokalen) en laadt dat in uw informatiesysteem. search/query houdt elke ophaalactie gefilterd, geprojecteerd en gepagineerd, voor een compact antwoord.
• Een push vanuit uw systeem — de omgekeerde richting, om Omniscol afgestemd te houden op uw bron van waarheid: een nachtelijke taak kan klassen en docenten bijwerken (POST /api/external/classes, POST /api/external/teachers) of een catalogus met aangepaste vakken (POST /api/admin/subjects/custom) uit uw database laden.
• Een SIS-/ERP-pakket — voor Aurion, Auriga en soortgelijke systemen is de daarvoor bedoelde connector de juiste tool — zie Synchronisatie met externe systemen.
• Gebeurtenisgestuurd — om op de hoogte gebracht te worden van een wijziging in plaats van in een lus te blijven bevragen, registreert u een hook — zie API-aanpassingen.

Houd elke integratie beperkt: een token dat begrensd is tot de endpoints die werkelijk nuttig zijn, dat regelmatig vernieuwd wordt, en alleen-lezen overal waar de integratie alleen leest. Zie Omniscol-API.