Students API

Titel	Students API
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming in beheer
Versie	Documentatie: 0.0.7
Versie	schemaVersion: 0.0.7
Datum	24 April 2024
Auteurs	Architectenraad Edu-V
Acties	Review en doorontwikkeling op basis van input LAS leveranciers

De Students API wordt gebruikt om persoonsgegevens over onderwijsdeelnemers uit het Administratiesysteem onderwijsdeelnemer te delen in het Afsprakenstelsel Edu-V. Deze API wordt aangeboden als onderdeel van de gegevensdienst Onderwijsdeelnemers met het Administratiesysteem onderwijsdeelnemer als Bron.

De technische specificatie bestaat uit:

1 Samenvatting
2 Object: Student (Onderwijsdeelnemer)
3 Status- en foutcodes
4 Technisch: API specificatie
5 Release notes

Samenvatting

Gegevensdienst	Onderwijsdeelnemers Onderwijsdeelnemers Demografie Onderwijsdeelnemers Communicatie Onderwijsdeelnemers Toegankelijkheid Onderwijsdeelnemers Adresgegevens fijndistributie
Scopes	student.basic student.demographics student.communication student.accessibility student.deliveryaddress
Objecten	Student StudentDemographics StudentCommunication StudentAccessibility StudentDeliveryAdress
Bron	Administratiesysteem onderwijsdeelnemer
Afnemer	Bestelomgeving leermiddelen Identiteitsbeheervoorziening Digitaal toetssysteem
Endpoints	Administratiesysteem onderwijsdeelnemer POST Search Student GET Student GET Students 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. Berichteninfrastructuur voor het versturen en ontvangen van berichten Notifications API

Object: Student (Onderwijsdeelnemer)

Het object Student beschrijft de identifiers, de namen van de onderwijsdeelnemer en overige kenmerken. Dit object is beschikbaar vanuit de scope student.basic.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
userMasterIdentifier	string	string	De primaire identifier voor de onderwijsmedewerker.	https://ketenid.nl/201703/1a5c9c7203901866532c2d72ce056e1d29cacc70836fe2bc3a517f3f9a53eed3d77ef370ad6dcf80b3f34ced1c547c7d2e679e8e47002355f938213b3656b206	V*	De werkingsregels is dat de primaire identifier wordt gehanteerd in het object. De primaire identifier voor onderwijsdeelnemer is het ECKiD. In geval van een uitzonderingssituatie kan gebruik gemaakt van een secundaire identifier.
userIds	array	userId	Een lijst van secundaire identifiers die gehanteerd kan worden als de primaire identifier ontbreekt.	[{userId: ‘pietjepukkelen@petteflatcollege', userIdType: 'nlEduPersonRealId’}] Zie referentie naar eindgebruiker	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.
givenName	string	string	De voornaam of voornamen van de onderwijsdeelnemer		V
preferredFirstName	string	string	De roepnaam van de onderwijsdeelnemer		V
familyName	string	string	De achternaam van de onderwijsdeelnemer		V
familyNamePrefix	string	string	Het tussenvoegsel uit de achternaam van de onderwijsdeelnemer		O
sourceId	string	string	Een unieke identifier die gegenereerd is door het Administratiesysteem onderwijsdeelnemer en binnen dit systeem uniek is.		V	De sourceId wordt gebruikt om informatie over dit object op te vragen in de koppelvlakspecificatie. Deze identifier is betekenisloos en daarmee geen persoonsgegeven.
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

Attributen: StudentDemographics

De StudentDemographics attributen bevatten demografische gegevens over de onderwijsdeelnemer. Dit object is alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen. Voor deze attributen geldt een separate scope student.demographics.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

gender

string

ENUm

Geslacht van de onderwijsdeelnemer. Er wordt een ENUM gehanteerd:

female
male
other
unspecified

unspecified

O

unspecified wordt gekozen indien de data niet beschikbaar is.

other wordt gekozen indien het geslacht wel bekend is maar geen female of male is.

dateOfBirth

string

date

Geboortedatum van de onderwijsdeelnemer.

2000-11-11

O

Attributen: StudentCommunication

De StudentCommunication attributen bevat het mailadres van de onderwijsdeelnemer bij de onderwijsaanbieder. Dit attribuut is alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor dit attribuut. Voor dit attribuut geldt een separate scope student.communication.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
email	string	string	Het e-mailadres van de onderwijsdeelnemer zoals beschikbaar gesteld door de onderwijsaanbieder	student@school.nl	V

Attributen: StudentAccessibility

De StudentAccessibility attributen bevat de voorkeuren van de onderwijsdeelnemer op het vlak van toegankelijkheid en talen. Deze attributen zijn alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen. Voor deze attributen geldt een separate scope student.accessibility.

Optioneel

Toegankelijkheid is een optioneel onderdeel van de Students API. Op basis van expliciete behoeften in ketenprocessen kunnen voorkeuren voor toegankelijkheid benut worden.

Er dient ook nader onderzocht te worden of toegankelijk op het niveau van een onderwijsdeelnemer zit of dat er ook een relatie is met een vak. Zodra dit laatste het geval is dan zal er ook gekeken moeten worden naar de Association API.

Veld

Type

Format

Omschrijving

Voorbeeld

O/V

Vullingsregel

language

string

De voorkeurstaal van de onderwijsdeelnemer.

nld

O

ISO369 set 3 waardes worden gehanteerd. Een voorbeeldlijst is beschikbaar op Wikipedia.

accessibility

array

AccessibilityPreference

Een voorkeur voor een toegankelijkheidsinstelling.

O

De voorkeuren worden gevuld op basis van de AfA of PnP voorkeuren zoals gedefineerd door 1EdTech.

In de YAML file is ter illustratie AdditionalTestingTime uitgewerkt.

Attributen: StudentDeliveryAddress

De StudentDeliveryAddress attributen bevat de adresgegevens van de onderwijsdeelnemers ten behoeve van de fijndistributie van fysieke leermiddelen. Deze attributen zijn alleen beschikbaar voor referentiecomponenten die doelbinding hebben voor deze attributen. Voor deze attributen geldt een separate scope student.deliveryaddress.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
address	object	address	Het afleveradres waar de fysieke leermiddelen voor de onderwijsdeelnemer kunnen worden bezorgd.	Zie address	O	Zie Order API voor een uitwerking van het address object.
emailPrivate	string	string	Het persoonlijk e-mailadres van de onderwijsdeelnemer		O
emailsParents	array	string	Een lijst met e-mailadressen van de wettelijk vertegenwoordigers van de onderwijsdeelnemer		O

object address

Alle adresgegevens zijn samengevoegd in een blok. Dit adres kan in Nederland en ook in het buitenland zijn.

Voorstel: Landcodes

Voorstel is om niet de ISO landcodes te hanteren maar de landcodes die in het Nederlandse onderwijs vaak gebruikt worden, onder meer door DUO. Het betreft een waardelijst van de RIVG zoals weergeven in tabel 34 Landen.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
street	string	string	Straatnaam van het adres	Rijnkade	V
houseNumber	integer	integer	Huisnummer	12	V	Huisnummer is verplicht.
houseNumberSuffix	string	string	Huisnummer toevoeging	a	O	Toevoeging is optioneel.
zipCode	string	string	Postcode	1000 AA	V	Waarde is bij een Nederlands adres volgens het patroon van 4 cijfers en 2 letters
city	string	string	De woonplaats	Arnhem	V
countryCode	string	string	Landcode	NL	O	Waarde is de Alpha-2 code (2 letters) uit de ISO 3166 standaard dat correspondeert met het land zoals aangegeven door het veld Country
country	string	string	Het land van het adres van de leerling	Nederland	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 bericht 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 Students 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: Filteropties voor de GET for School endpoints toegevoegd.
0.0.4: HuisnummerToevoeging stond niet correct in de YAML. De naam van de voorkeur voor toegankelijkheid ontbrak in de YAML. Beide punten zijn gecorrigeerd.
0.0.5: 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.
0.0.6: De separate endpoints voor de diverse scopes zijn gecombineerd in een enkel endpoint. Ook is een endpoint toegevoegd om een onderwijsmedewerker op te vragen op basis van een userId en een userIdType.
0.0.7: preferredFirstName attribuut toegevoegd aan object Student en name verwijderd uit object DeliveryAdress.