Education API

Titel

Education API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.9.1

schemaVersion: 0.9.1

Datum

27 September 2024

Auteurs

Architectenraad Edu-V

Acties

  • Review en doorontwikkeling op basis van input LAS leveranciers

De Education API wordt gebruikt om informatie over aangeboden opleidingen en vakken uit het Administratiesysteem onderwijsdeelnemer te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsaanbod met het Administratiesysteem onderwijsdeelnemer als Bron.

Scope: werkingsgebieden funderend onderwijs en vavo

De afspraken met betrekking tot de gegevensdiensten uit de administratiesystemen zijn van toepassing op de werkingsgebieden:

  • Primair onderwijs

  • Gespecialiseerd onderwijs

  • Voortgezet onderwijs

  • Voortgezet algemeen volwassenenonderwijs (vavo)

De gegevensdiensten zijn niet ontwikkeld voor het middelbaar beroepsonderwijs. In het middelbaar beroepsonderwijs wordt gebruik gemaakt van OOAPI.

De technische specificatie bestaat uit:

Samenvatting

Gegevensdienst

Onderwijsaanbod

Scopes

  • eduv.education

Objecten

Bron

Administratiesysteem onderwijsdeelnemer

Afnemer

  • Selectieomgeving leermiddelen

  • Bestelomgeving leermiddelen

  • Aanspraakmanager

  • Leermiddelenportaal

  • Onderwijsleeromgeving

  • Leermiddelendashboard

  • Identiteitsbeheervoorziening

Endpoints

Administratiesysteem onderwijsdeelnemer

  • GET Organisation

  • GET Organisations

  • GET StudyOffering

  • GET StudyOfferings for School

  • GET SubjectOffering

  • GET SubjectOfferings for School

Notifications

De Notifications API kan gebruikt worden om als afnemer een notificatie te ontvangen bij een wijziging in de stand (nieuw/gewijzigd/verwijderd). Hiervoor dient zowel de bron als de afnemer dan de Berichteninfrastructuur en de Notifications API te hebben geïmplementeerd.

Object: Organisation (Onderwijsaanbieder)

Het object Organisation beschrijft een onderwijsaanbieder die als administratieve eenheid beschikbaar is in het Administratiesysteem onderwijsdeelnemer.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

organisation
MasterIdentifier

string

string

De primaire identifier voor een onderwijsaanbieder.

104A158

V*

De werkingsregels is dat de primaire identifier wordt gehanteerd in het object.

De primaire identifier voor onderwijsaanbieders is de OnderwijsaanbiederCode.

In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier.

organisationIds

array

organisationId

Een lijst van secundaire identifiers die gehanteerd kan worden als de primaire identifier ontbreekt.

[{organisationId: ‘09QQ00', organisationIdType: 'Vestigingserkenning’}]

V*

Zodra een secundaire identifier voor een uitzonderingssituatie gehanteerd wordt dan wordt naast het Id ook het Type gespecificeerd.

Zie de pagina Identiteiten voor de toegestane secundaire identifiers.

name

string

string

De naam van de onderwijsaanbieder

Marienbornschool

V

 

boards

array

BoardReference

Referenties naar de onderwijsbesturen waaronder deze onderwijsaanbieder valt.

Zie referentie naar onderwijsorganisatie

O

 

locations

array

LocationReference

Referentie naar de onderwijslocaties waar deze onderwijsaanbieder onderwijs aanbiedt.

Zie referentie naar onderwijsorganisatie

O

 

sourceId

string

string

Een unieke identifier die gegenereerd is door het Administratiesysteem onderwijsdeelnemer.

 

V

De sourceId wordt gebruikt om informatie over dit object op te vragen in de koppelvlakspecificatie.

status

string

ENUM

De status van dit object.

active
tobedeleted

V

De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.

dateCreated

string

datetime

Datum en tijdstip waarop de entiteit is aangemaakt

2017-07-21T17:32:28Z

V

 

dateLastModified

string

datetime

Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd

2022-08-11T15:31:12Z

V

 

Object: StudyOffering (AangebodenOpleiding)

Het object StudyOffering beschrijft de opleidingen op basis van de opleidingseenheden in combinatie met het leerjaar aangeboden door de onderwijsaanbieder. In het object worden verwijzingen gemaakt naar de waardelijsten die onder beheer zijn van de werkgroep Waardelijsten RIO.

*Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

studyOfferingId

string

uuid

Een unieke identifier voor het object

 

V

 

studyOfferingName

string

string

De naam die de onderwijsaanbieder heeft gegeven aan deze AangebodenOpleiding.

Gymnasium brugklas

V

 

studyName

string

string

De opleidingseenheid korte naam erkende opleiding die van toepassing is op deze AangebodenOpleiding.

vwo-gymnasium-onderbouw

V*

Indien de AangebodenOpleiding erkend is dan is dit veld verplicht.

Werkingsregel is om per sector de volgende waardelijsten te gebruiken:

  • Primair onderwijs: po-opleidingseenheden korte naam conform erkende opleiding in waardelijst RIO po

  • Voortgezet onderwijs: vo-opleidingseenheden korte naam conform erkende opleiding in waardelijst RIO vo

studyCode

string

string

De erkendeopleidingscode (po en vo) van de AangebodenOpleiding,

0200

V*

Indien de AangebodenOpleiding erkend is dan is dit veld verplicht.

Werkingsregel is om per sector de volgende waardelijsten te gebruiken:

studyCharacteristics

array

string

De opleidingskenmerken van deze AangebodenOpleiding.

Begaafdheidsprofiel

Montessori

O

Werkingsregel is om per sector de volgende waardelijsten te gebruiken:

studyLevel

object

StudyLevel

Het onderwijsniveau van deze AangebodenOpleiding.

Zie StudyLevel object

O

Formaat conform het Niveau van SLO. Voor meer informatie zie Waardelijst onderwijsniveaus en leerjaren.

studyYear

integer

integer

Het opleidingsjaar van deze AangebodenOpleiding

1

O

Dit attribuut specificeert het jaar van de opleiding. Bijvoorbeeld:

  • Basisonderwijs: 0, 1, 2, 3, 4, 5, 6, 7 of 8

  • VMBO: 0, 1, 2, 3 of 4

  • HAVO: 0, 1, 2, 3, 4 of 5

  • VWO: 0, 1, 2, 3, 4, 5 of 6

Het gespecialiseerd onderwijs kan optioneel gebruik maken van dit attribuut. Uit het studyLevel valt op te maken dat de opleiding van het niveau speciaal onderwijs of voortgezet speciaal onderwijs is.

status

string

ENUM

De status van dit object.

active
tobedeleted

V

De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.

dateCreated

string

datetime

Datum en tijdstip waarop de entiteit is aangemaakt

2017-07-21T17:32:28Z

V

 

dateLastModified

string

datetime

Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd

2022-08-11T15:31:12Z

V

 

Object: SubjectOffering (AangebodenVak)

Het object SubjectOffering beschrijft de vakken aangeboden door de onderwijsaanbieder. In het object worden verwijzingen gemaakt naar de waardelijsten die onder beheer zijn van de werkgroep Waardelijsten RIO.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

subjecOfferingtId

string

uuid

Een unieke identifier voor het object

 

V

 

subjectOfferingName

string

string

De naam die de onderwijsaanbieder heeft gegeven aan dit vak.

Cambridge Engels

V

 

subjectOfferingAbbr

string

string

De afkorting voor dit vak

en

O

 

subjectCode

string

string

De vakcode voor dit vak.

 

V*

Indien het vak onderdeel is van het curriculum uit een opleiding dan is dit veld verplicht.

Er vindt overleg plaats met de werkgroep Waardelijsten RIO voor het opstellen van een lijst met vakcodes voor veelvoorkomende vakken in het po en vo.

studyOfferings

array

string

Een referentie naar de AangebodenOpleiding (StudyOffering) objecten waar dit AangebodenVak onder valt.

 

V*

Verwijzing naar studyOfferingId

Indien het vak onderdeel is van het curriculum uit een opleiding dan is dit veld verplicht.

status

string

ENUM

De status van dit object.

active
tobedeleted

V

De status is een verplicht veld en geef aan of het object al dan niet verwijderd kan worden.

dateCreated

string

datetime

Datum en tijdstip waarop de entiteit is aangemaakt

2017-07-21T17:32:28Z

V

 

dateLastModified

string

datetime

Tijdstempel waarop één of meerdere van de hierboven genoemde attributen het laatst zijn gewijzigd

2022-08-11T15:31:12Z

V

 

Status- en foutcodes

Voor alle APIs uit het Afsprakenstelsel Edu-V zijn de status- en foutcodes beschreven op de pagina Status- en foutcodes. Hierbij is onderscheid gemaakt in algemene en voor de API specifieke status- en foutcodes.

Technisch: API specificatie


Release notes

  • 0.0.1: De Rostering API was voorheen een onderdeel van de SIS API. Hierin waren de volgende wijzingen gedaan:

    • 0.0.1: Eerste draft van de API.

    • 0.0.2: Objecten en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.

    • 0.0.3: De technische specificatie is verder uitgewerkt. Ook is de feedback uit de werkgroepen verwerkt in een volgende versie:

      • GET all endpoints zijn toegevoegd voor alle objecten.

      • Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van regie op gegevens en de M2M identificatie en authenticatie.

      • Object Teacher is hernoemd naar Employee inclusief het attribuut role. In dezelfde lijn is ook teacherReference hernoemd naar employeeReference

      • De waardelijst studyYear is verduidelijkt.

      • Het attribuut class van de Student is een separaat object geworden inclusief employees.

      • De status- en foutcodes zijn toegevoegd aan de documentatie en de YAML.

      • In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.

      • De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.

    • 0.0.4: Objecten geactualiseerd op basis van herziening rollen en referentiecomponenten in het architectuurkader.

    • 0.0.5: Terminologie in YAML bijgewerkt.

    • 0.0.6: Gegevensdiensten van SIS API opgesplitst in:

      • Onderwijsorganisatie

      • Adresgegevens fijndistributie

      • Onderwijsaanbod

  • 0.0.2: De Education API is opgesteld op basis van een herziening van de SIS API. In deze herziening is aansluiting gezocht bij de best practices uit bestaande standaarden en een uiteenzetting van ontwerpeisen vanuit de flexibilisering van het onderwijs.

  • 0.0.3: De benamingen zijn gewijzigd naar StudyOffering en SubjectOffering.

  • 0.0.4: De volgende wijzigingen zijn gedaan:

    • Wijzigingen in de architectuur:

      • Attribuut schemaVersion is verwijderd uit de objecten.

      • Query parameter schemaVersion is verwijderd uit de koppelvlakken.

      • Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.

      • Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.

    • Wijzigingen in de documentatie en de YAML:

  • 0.0.5: Query parameter name toegevoegd aan GET organisations om zoeken van organisaties op naam mogelijk te maken.

  • 0.0.6: StudyAbbr attribuut verwijderd uit de StudyOffering object.

  • 0.0.7: studyCharacteristics attribuut van StudyOffering verandert in een array. Pattern voor studyCode verwijderd uit de YAML. De studyCode kan verschillende vormen hebben in RIO.

  • 0.0.8: Het attribuut studyYears (array) is vervangen door het attribuut studyYear (enkele waarde). Een eerder wijzigingsvoorstel is ingetrokken en weer teruggebracht naar de eerdere versie.

  • 0.0.9: Toelichting op opleidingsjaar (studyYear) aangepast in de tabel en in de YAML.

  • 0.9.0: Het Bestuurlijk Overleg heeft tijdens de bijeenkomst van 27 juni 2024 het Afsprakenstelsel Edu-V als versie 0.9.0 goedgekeurd voor implementatie.

  • 0.9.1: Wijzigingen naar aanleiding van RFC’s:

    • Op basis van RFC002 is de scope aangepast met een prefix eduv.. Dit stelt leveranciers in staat om onderscheid te maken tussen gegevensuitwisselingen met leveranciers binnen en buiten het Edu-V afsprakenstelsel.

    • De parameters voor paginering zijn uit de koppelvlakspecificatie verwijderd. Binnen het afsprakenstelsel zijn de afspraken hierover beschreven op de pagina paginering, sorteren en rate limiting.

    • In de documentatie bij het attribuut studyYear van het object StudyOffering in de documentatie voor de volledigheid ook leerjaar 0 toegevoegd.

    • De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.