Overzicht & scope

EKOC (Eduarte Koppeling Onderwijscatalogus) is een lezen-en-schrijven REST-API voor het beheer van de onderwijscatalogus: resultaatstructuren, toetsen, onderwijsproducten, opleidingen (met cohorten) en de bijbehorende referentiesoorten. De API levert JSON en volgt de gemeenschappelijke Connect-conventies.

• Versie: 1.0
• Pad-prefix: /connect/ekoc/1_0

Deze specificatie beschrijft de technische uitgangspunten en geeft een overzicht op hoofdlijnen. De volledige OpenAPI-specificatie van EKOC wordt niet publiek gepubliceerd; neem voor de volledige endpoint- en schemadefinities contact op met Eduarte (connect@eduarte.nl).

Aan de slag & dev-omgeving

1. Toegang aanvragen — vraag via Eduarte (connect@eduarte.nl) OAuth2-clientgegevens aan voor EKOC.
2. Scope — EKOC gebruikt de scope onderwijscatalogus (lezen en schrijven).
3. Token ophalen — haal een access-token op via de OAuth2 Client Credentials-flow.
4. Aanroepen — stuur het token mee als Authorization: Bearer <token> en roep endpoints aan onder /connect/ekoc/1_0.
5. Testen — gebruik de beschikbare ontwikkel-/testomgeving voordat je in productie gaat.

Beveiliging

Alle Connect API’s worden uniform beveiligd. De maatregelen hieronder gelden voor elke connector; afwijkingen staan in de connector-specifieke secties.

Transport (TLS)

Alle communicatie verloopt verplicht via HTTPS. Minimaal TLS 1.2, bij voorkeur TLS 1.3. Er zijn geen HTTP-endpoints, ook niet voor redirects. Een geldig servercertificaat is vereist. Hierin volgen we de aanbeving van de NSCT

Authenticatie & autorisatie

Authenticatie verloopt via OAuth 2.0 met de Client Credentials-flow (server-to-server):

• Token-endpoint: https://login.educus.nl/oauth2/token?organisatieuuid=<uuid>
• De client wisselt zijn client_id en client_secret in voor een access-token.
• Het verkregen token wordt bij elke aanroep meegestuurd in de Authorization: Bearer <token>-header.

Scopes bepalen de toegangsrechten volgens het principe van least privilege. Elke API kent één of meer scopes; een token bevat alleen de scopes die de client nodig heeft. De vereiste scope(s) per connector staan in de connector-specifieke sectie.

Waar OAuth 2.0 niet mogelijk is (bijvoorbeeld bij legacy-integraties), kan als terugvaloptie een Bearer-token (JWT) worden gebruikt.

Per endpoint

Elk endpoint heeft een expliciete security-definitie. Onjuiste of ontbrekende autorisatie leidt tot een 401 Unauthorized (niet geauthenticeerd) of 403 Forbidden (onvoldoende rechten); zie Foutafhandeling.

Conventies & ontwerpprincipes

De Connect API’s volgen gemeenschappelijke conventies, zodat integraties voorspelbaar en consistent zijn.

Formaat & naamgeving

• JSON is het representatieformaat voor requests en responses.
• Resources zijn meervoud en in camelCase: /fases, /organisatieeenheden.
• Path-parameters zijn camelCase: /fases/{id}.
• Query-parameters zijn lowercase kebab-case (uitzondering: het historische pageSize).
• Schema-namen zijn PascalCase; properties zijn camelCase.

Paginering

Lijst-endpoints zijn gepagineerd (offset-based):

De response bevat een meta-object met offset, pageSize en totalItems, plus een items-array. Een leeg resultaat geeft een lege items-array terug — geen 404.

{
  "meta": { "offset": 20, "pageSize": 10, "totalItems": 156 },
  "items": [ { "id": "..." } ]
}

Versionering

Versies volgen SemVer in de vorm MAJOR.MINOR. De major-versie staat in het pad (bv. /connect/eks/v1_0/...). Non-breaking wijzigingen (nieuw optioneel veld, nieuw endpoint, nieuwe enum-waarde) verschijnen als minor-versie binnen dezelfde major; breaking wijzigingen leiden tot een nieuwe major-versie die parallel draait. Bij uitfasering gelden een deprecation-notice en een sunset-datum (minimaal 6 maanden), gecommuniceerd via Deprecation- en Sunset-headers.

Afhankelijkheden & validatie

De onderwijscatalogus kent onderlinge samenhang; houd hier rekening mee bij schrijfacties:

• Een resultaatstructuur vereist minimaal: code, naam, type, cohort, onderwijsproduct en toets.
• De combinatie code + cohort + onderwijsproduct van een resultaatstructuur is uniek.
• Een toets hoort bij een resultaatstructuur.
• Bij verwijderen gelden afhankelijkheidscontroles; een object dat nog in gebruik is, kan niet zomaar worden verwijderd (verwacht in dat geval een foutresponse).

Wijzigingen ophalen

Wijzigingen in de onderwijscatalogus (onderwijsproducten, opleidingen, toetsen, resultaatstructuren e.d.) worden in de toekomst gesignaleerd via de notificatiekoppeling EKN met cloudevents, zodat een afnemer gericht de nieuwe stand kan ophalen. Deze notificaties zijn nog niet beschikbaar. EKOC kent (nog) geen changed-since-parameter; tot die tijd haal je de actuele stand op via de lijst-endpoints.

Do’s & don’ts

Praktische richtlijnen voor een robuuste integratie met Connect.

Do’s

• Gebruik paginering bij het ophalen van lijsten; doorloop pagina’s via offset/pageSize.
• Hergebruik access-tokens binnen hun geldigheidsduur in plaats van bij elke aanroep een nieuw token op te halen.
• Handel fouten af op basis van de HTTP-statuscode en het problem+json-foutobject, niet op tekst.
• Implementeer backoff bij 429 Too Many Requests en respecteer de Retry-After-header.
• Pin op een major-versie in het pad en test tegen de testomgeving vóór productie.
• Cache referentie-/stamdata waar passend, omdat deze weinig verandert.

Don’ts

• Geen polling zonder backoff — vermijd onnodige herhaalde aanroepen in korte tijd.
• Geen hardcoded URLs zonder versie — verwijs altijd naar het versie-pad.
• Vertrouw niet op niet-gedocumenteerde velden of op de volgorde van items zonder expliciete sortering.
• Stuur geen gevoelige gegevens in query-parameters of logregels.
• Ga niet uit van directe consistentie tussen los opgehaalde resources.

Bron: API-CONVENTIONS.md (o.a. “Wanneer niet suppressen”) en de Connect REST-principes.

Foutafhandeling

Foutmeldingen zijn gestandaardiseerd op basis van RFC 7807 (Problem Details for HTTP APIs). Hierdoor zien fouten er over alle Connect API’s hetzelfde uit.

• Alle fouten hebben mediatype application/problem+json.
• Elke fout bevat een compacte JSON-body met een omschrijving en details.
• Elke operatie definieert ten minste de onderstaande fouten.

Voorbeeld (401)

{
  "type": "https://tools.ietf.org/html/rfc6750#section-3.1",
  "title": "Unauthorized",
  "status": "401",
  "detail": "The request requires user authentication."
}

Veelvoorkomende statuscodes

Let op: API’s uit de keten (OKxx) volgen de foutafhandeling van hun eigen standaard (bv. OOAPI) en kunnen hiervan afwijken.

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:

Aanbevolen client-gedrag

• Respecteer Retry-After en 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.

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.

Endpoints op hoofdlijnen

Alle lijst-endpoints zijn gepagineerd (zie Conventies).

Catalogusbeheer (lezen + schrijven)

Referentiegegevens (alleen lezen)

Voor de volledige parameter-, response- en schemadefinities: neem contact op met Eduarte (connect@eduarte.nl).

Versiebeheer & changelog

EKOC volgt de Connect-versioneringsstrategie (SemVer, major-versie in het pad). De huidige versie is 1.0. Non-breaking wijzigingen verschijnen als minor-versie binnen dezelfde major; breaking wijzigingen leiden tot een nieuwe major-versie die parallel draait, met een deprecation-notice en sunset-datum.