OKE — Examens
Overzicht & scope
OKE (Onderwijs Koppeling Examinering — “MBO-toetsafname”) is een toepassingsprofiel op OOAPI v5 voor de gegevensuitwisseling in het MBO-examenproces. Het volgt de landelijke OOAPI/NED-conventies (Engelstalig, REST/JSON). De gezaghebbende definitie staat extern:
Officiële standaard: https://github.com/NetwerkExamineringDigitalisering/NED-OOAPI
Deze specificatie beschrijft OKE zoals geïmplementeerd in Eduarte Connect en verwijst voor de volledige definitie, schema’s en conventies naar de officiële standaard.
- Standaard: OOAPI v5 / NED-OOAPI (MBO-toetsafname)
- Versie: 1.0.1 (versie 1.0 inclusief informatiestroom 6)
- Volledige OpenAPI-specificatie: meegeleverd
als
OKE_v1.0.yml. - Interactieve referentie online: API-referentie van OKE
Status. OKE is niet meer in ontwikkeling, met uitzondering van informatiestroom 6 (Analyse-informatie).
Rollen & informatiestromen
Eduarte vervult in OKE twee rollen (een dubbele koppeling): Deelnemerregistratie (SIS) en Toetsplanning (TPL). Welke informatiestromen worden ondersteund, verschilt per rol:
| Rol | Informatiestromen |
|---|---|
| OKE als SIS | 0 Toetscatalogus · 1 Toetsdeelnemers · 5 Studentresultaat · 6 Analyse-informatie |
| OKE als TPL | 0 Toetscatalogus · 2 Zittingsplan · 3 Toetsdeelnemerresultaat · 4 Zittingsverslag |
Zie het productdocument voor de volledige beschrijving van de keten en de informatiestromen.
Aan de slag & dev-omgeving
- Toegang aanvragen — vraag via Eduarte (connect@eduarte.nl) toegang aan voor OKE en geef aan in welke rol(len) je aansluit (SIS en/of TPL).
- Authenticatie — OKE wordt beveiligd via OAuth2 conform het Edukoppeling REST-profiel (zie Beveiliging).
- Aanroepen — roep de OOAPI-endpoints aan
(zie Endpoints op hoofdlijnen); de exacte base-URL
staat in de meegeleverde
OKE_v1.0.yml. - Testen — gebruik de beschikbare ontwikkel-/testomgeving voordat je in productie gaat.
Beveiliging
OKE volgt de beveiliging van de OOAPI/NED-standaard:
- Alle communicatie verloopt via HTTPS/TLS.
- Authenticatie en autorisatie via OAuth2, conform het Edukoppeling REST-profiel (zoals ook in de OKx-/OKD-koppelingen gebruikt).
- Raadpleeg de officiële standaard en de meegeleverde specificatie voor de exacte security-schemes en scopes.
Conventies (OOAPI v5)
OKE volgt de OOAPI v5-conventies, die afwijken van de Connect-conventies van de E-koppelingen:
- Engelstalige resources en velden, REST/JSON volgens OAS 3.
- Paginering, filtering, sortering en het uitbreiden van
objecten (
expand) volgens OOAPI. - OOAPI-objectmodel: aanbod loopt via het offering-endpoint (program-/course-/component- offering) en relaties via het association-endpoint.
Raadpleeg de officiële standaard en de meegeleverde specificatie voor de exacte conventies, parameters en schema’s.
Foutafhandeling
OKE volgt de foutafhandeling van de OOAPI/NED-standaard (niet het Connect-foutmodel van de E-koppelingen). Zie de officiële specificatie voor de foutstructuur en statuscodes.
Throttling & rate limiting
Alle endpoints kennen rate limiting om misbruik en overbelasting te voorkomen. Dit wordt op infrastructuurniveau afgedwongen via de Topicus API-gateway.
Bij overschrijding van de limiet antwoordt de API met
429 Too Many Requests. De response
kan de volgende headers bevatten:
| Header | Betekenis |
|---|---|
Retry-After |
Aantal seconden tot een volgende aanroep is toegestaan |
X-RateLimit-Limit |
Maximum aantal aanroepen per tijdsperiode |
X-RateLimit-Remaining |
Resterend aantal aanroepen in de huidige periode |
Aanbevolen client-gedrag
- Respecteer
Retry-Afteren wacht ten minste het opgegeven aantal seconden. - Gebruik exponential backoff met jitter bij
herhaalde
429-responses. - Verspreid bulk-aanroepen over de tijd in plaats van ze gelijktijdig te versturen.
Endpoints op hoofdlijnen
Zoals geïmplementeerd in Eduarte Connect (OOAPI-objecten).
Voor de volledige definities: zie de meegeleverde
OKE_v1.0.yml of de officiële standaard.
| Endpoint | Toelichting |
|---|---|
/persons/{personId} |
Persoon (deelnemer of medewerker) |
/organizations/{organizationId} |
Organisatorische eenheid |
/components ·
/components/{componentId} |
Onderdelen van het aanbod |
/offerings ·
/offerings/{offeringId} |
Aanbod (program-/course-/componentOffering) |
/offerings/{offeringId}/associations |
Associaties bij een offering |
/associations/{associationId} ·
/associations/{associationId}/url |
Associatie (inschrijving/relatie) |
/groups · /groups/{groupId} ·
/groups/{groupId}/members |
Groepen en hun leden |
/documents/{documentId} |
Document bij de toetsafname |
Versiebeheer & standaard
OKE is gebaseerd op OOAPI v5; versionering en wijzigingen volgen de landelijke NED-standaard.
| Aspect | Waarde |
|---|---|
| Standaard | OOAPI v5 / NED-OOAPI (MBO-toetsafname) |
| Versie in Eduarte Connect | 1.0.1 (versie 1.0 inclusief informatiestroom 6) |
| Bron | https://github.com/NetwerkExamineringDigitalisering/NED-OOAPI |
| Status | Niet meer in ontwikkeling, behalve informatiestroom 6 (Analyse-informatie) |
Beschikbaarheid & SLA
Eduarte Connect wordt aangeboden als beheerde dienst. Beschikbaarheid, onderhoud en support zijn vastgelegd in de partnerovereenkomst en bijbehorende SLA.
Uitgangspunten
- De API’s zijn ontworpen voor continue beschikbaarheid tijdens kantoor- en lesuren.
- Gepland onderhoud wordt vooraf aangekondigd via de gangbare communicatiekanalen en zo veel mogelijk buiten piekuren uitgevoerd.
- Storingen en vragen kunnen worden gemeld bij Eduarte via de beklende servicedesk meldingen
- Partner vragen kunnen worden gemeld bij info@eduarte.nl.
Let op: concrete SLA-cijfers (beschikbaarheidspercentage, reactietijden, onderhoudsvensters) worden vastgelegd in de partnerovereenkomst en zijn nog te bevestigen voor deze documentatie.