Notifications API

Titel	Notifications API
Status	IN ONTWIKKELING ROSA-ARCHITECTUURSCAN BESLUITVORMING IN BEHEER
Versie	0.0.7
Datum	31 Januari 2024
Auteur	Architectenraad Edu-V
Acties	Geen openstaande acties

De Notifications API is de technische implementatie van het transactiepatroon Abonneren op wijzigen middels notificaties.

De technische specificatie bestaat uit:

Samenvatting

Scopes	catalogue course school student-employee-group student-delivery
Bron	Leveranciersspecifieke Leermiddelencatalogus Leermaterialencatalogus Administratiesysteem onderwijsdeelnemer
Afnemer	Selectieomgeving leermiddelen Bestelomgeving leermiddelen Aanspraakmanager Distributiefaciliteit Licentieregistratie Gebruiksomgeving digitaal leermateriaal Digitaal toetssyteem Leermiddelenportaal Onderwijsleeromgeving Leermiddelendashboard
Berichten	Notification
Endpoints	Producer (Bron) POST Subscribe to notifications for new/modified/deleted data objects from an API GET Get notifications after created datetime Consumer (Afnemer) POST Receive one notification POST Receive notifications

Berichtdefinitie: Notification

Een Notificatie bevat alle informatie ten behoeve van de berichteninfrastructuur om deze als Leverancier correct te kunnen verwerken.

Bij het versturen van Notificatie berichten hanteren we de volgende afspraken:

Zodra er meerdere Notificaties tegelijkertijd worden verstuurd dan zijn ze gesorteerd op volgorde van aanmaken (veld created), de oudste notificaties als eerste.
Notificaties worden gestuurd na een gebeurtenis en het aanmaken van een dataobject (bijvoorbeeld een nieuwe, gewijzigde of verwijderde entiteit). Al deze Notificaties dienen te worden verwerkt door de ontvanger.
Iedere Notificatie heeft een eigen unieke identifier id en de identifier van het dataobject objectId.
In het veld created is een tijdstempel opgenomen van de actie die als trigger heeft gediend voor de notificatie. Deze tijdstempel betreft niet het moment van versturen of verwerken van de notificatie. Dit veld kan door de Ontvanger gebruikt worden om notificaties op volgorde te verwerken.
Voor het verwijderen van een dataobject kan door de Verzender gebruik gemaakt worden van het veld isDeleteNotification met de waarde True. Dit is tevens het signaal voor de Ontvanger dat er geen verdere notificaties meer verstuurd worden voor dit dataobject.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
id	string	uuid	Unieke identifier voor deze notificatie	d290f1ee-6c54-4b01-90e6-d701748f0851	V
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
objectType	string	ENUM	Het type object waarvan een notificatie wordt verstuurd.	Student StudentDelivery Employee Class Group SchoolPeriod SchoolSubject Product Course	V
objectId	string	string	Identifier van het dataobject dat wordt verstuurd in het Event.	-	O	Is verplicht bij isDeleteEvent
userIdType	string	ENUM	Het type userId dat wordt gehanteerd in het veld objectId, indien het object een user betreft.	ECKiD nlPersonProfileId nlPersonRealId Las-key BasispoortId Medewerkernummer	O*	Indien het dataobject een Student, Employee of StudentDelivery betreft, dan wordt hier gespecificeerd welke type userId is gehanteerd als objectId
schoolId	string	string	Identifier van de onderwijsorganisatie waartoe het dataobject behoort.		O*	Indien het dataobject uit de SIS API komt dan is dit veld verplicht. De schoolId dient te worden gebruikt om het object op te vragen.
schoolPeriod	string	string	Referentie naar schoolperiode	2021-2022	O*	Referentie naar schoolPeriod.name Indien het dataobject uit de SIS API komt dan is dit veld verplicht. Dit stelt de Ontvanger in staat om het nieuwe, gewijzigde of verwijderde dataobject voor de correcte schoolperiode op te vragen.
edu_org_id	string	string	Onderwijsorganisatie waarop de consent is geregistreerd voor de uitwisseling van het data object.		O*	Indien het dataobject uit de SIS API komt dan is dit veld verplicht. De edu_org_id dient te worden gebruikt om het object op te vragen.
created	string	datetime	Tijdstempel van actie die als trigger heeft gediend voor de notificatie	2017-07-21T17:32:28Z	V
url	string	string	URL naar het endpoint om het nieuwe of gewijzigde dataobject op te halen.		O
isDeleteNotification	boolean	boolean	Indicatie voor de ontvanger dat dit het laatste bericht is betreffende dit dataobject aangezien deze verwijderd is.	True of False	O

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: Eerste draft van de API.
0.0.2: Berichtdefinities en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.
0.0.3: De technische specificatie is verder uitgewerkt.
- edu_org_id is toegevoegd aan alle endpoints als implementatie van regie op gegevens en de M2M identificatie en authenticatie.
- De Events API is herschreven naar het transactiepatroon Abonneren op wijzigingen middels notificaties.
  - Producer heeft een endpoint subscribe en een endpoint voor Consumers om notificaties na een bepaalde tijdstempel op te vragen.
  - Consumer heeft endpoint om een notificatie te ontvangen en een endpoints om notificaties te ontvangen.
- De status- en foutcodes zijn toegevoegd aan de documentatie en aan 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: De school periode is toegevoegd aan het notificatiebericht. Dit stelt de ontvanger in staat om het gewijzigde, nieuwe of verwijderde data object van een specifiek schooljaar op te vragen.
0.0.5: Naam van de API gewijzigd naar Notifications API.
0.0.6: Course API is toegevoegd als optie om een notificatie voor te ontvangen en je op te abonneren.
0.0.7: De pagina is besproken tijdens de bijeenkomst van de Architectenraad Edu-V en is gereed voor de ROSA-architectuurscan.