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 |
|
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 |
|
Objecten | |
Bron | Administratiesysteem onderwijsdeelnemer |
Afnemer |
|
Endpoints | Administratiesysteem onderwijsdeelnemer
|
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 | 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. | O | Â | |
locations | array | LocationReference | Referentie naar de onderwijslocaties waar deze onderwijsaanbieder onderwijs aanbiedt. | 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 | 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:
|
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:
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 | 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 | 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:
Objecten in documentatie en YAML gecontroleerd.
studyLevel gewijzigd naar het object studyLevel zoals gespecificeerd in de waardelijst onderwijsniveaus en leerjaren.
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 objectStudyOffering
in de documentatie voor de volledigheid ook leerjaar 0 toegevoegd.De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.