Events API

Titel	Events API
Status	DRAFT ARCHITECTENRAAD REDACTIE BESLUITVORMING CONCEPT
Stadium	POC PILOT BEHEER
Versie	0.0.1
Datum	25 Mei 2023
Auteur	Architectenraad Edu-V
Acties	De Events API is op dit moment uitgewerkt met FAT events. Dit wordt gewijzigd conform het transactiepatroon van Edukoppeling naar Notificaties met een url naar een GET endpoint om de laatste status op te halen. Endpoint abonneeservice toevoegen conform het transactiepatroon van Edukoppeling. Toevoegen van veld SchoolIdentifier aan Event ter validatie van (de)activering gegevensuitwisseling op Resource server?

De technische specificatie bestaat uit:

Samenvatting

Scopes	la.catalogue sis.school sis.student-teacher-group sis.student-delivery ls.entitlement
Producer	Leermiddelenaanbieder – Leveranciersspecifieke Leermiddelencatalogus Administratiesysteemaanbieder – Administratiesysteem onderwijsdeelnemers Leermiddelenshop – Faciliteit voor leveren (of arrangeren) van digitale leermiddelen
Consumer	Leermiddelenaanbieder Leermiddelenshop Leerportaalaanbieder Dashboardaanbieder
Berichten	Event
Endpoints	POST Receive events POST Receive one event POST Request Initial Seed GET Get Events GET Get SchemaVersions

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

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

In het veld data wordt het dataobject waarvoor een event wordt verstuurd opgenomen. Dit is conform het type bericht behorende bij het dataobject. Het type bericht is opgenomen in het veld type en de gehanteerde schemaversie in het veld schemaVersion.
Zodra er meerdere Events tegelijkertijd worden verstuurd dan zijn ze gesorteerd op volgorde van aanmaken (veld created), de oudste events als eerste.
In het Ecosysteem worden Events gestuurd na een gebeurtenis en het aanmaken van een dataobject (bijvoorbeeld een nieuwe, gewijzigde of verwijderde entiteit). Al deze Events dienen te worden verwerkt door de ontvanger.
Ieder Event 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 het event. Deze tijdstempel betreft niet het moment van versturen of verwerken van het event. Dit veld kan door de Ontvanger gebruikt worden om berichten op volgorde te verwerken.
Voor het verwijderen van een dataobject kan door de Verzender gebruik gemaakt worden van het veld isDeleteEvent met de waarde True. Het veld data kan in dat geval leeg blijven en alleen het veld objectId is dan verplicht. Dit is tevens het signaal voor de Ontvanger dat er geen verdere berichten meer verstuurd worden voor dit dataobject.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
id	string	uuid	Unieke identifier voor Event	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
type	string	ENUM	Het type bericht dat via dit Event wordt verstuurd.	Alle Events zoals opgenomen in deze documentatie	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 Leerlingnummer Medewerkernummer	O*	Indien het object een Student, Teacher of StudentDelivery betreft, dan wordt hier gespecificeerd welke type userId is gehanteerd als objectId
created	string	datetime	Tijdstempel van actie die als trigger heeft gediend voor het event	2017-07-21T17:32:28Z	V
data	object	-	Het dataobject dat conform de bijbehorende berichtdefinitie wordt verstuurd.	-	O	Kan leeg blijven bij isDeleteEvent
isDeleteEvent	boolean	boolean	Indicatie voor de ontvanger dat dit het laatste bericht is betreffende dit dataobject aangezien deze verwijderd is.	True of False	O

Status code	Status	statusMessage	Toelichting
200	0	OK	Bericht succesvol verwerkt
400	1	Failing event	Schemavalidatie niet succesvol
400	2	schemaVersion not supported	De ontvanger kan de gehanteerde SchemaVersion niet verwerken
401	3	scope required	Verzender is niet geautoriseerd voor scope
403	4	consent required	De gegevenssoort is van classificatie IV. Dit vereist een activering van de gegevensuitwisseling. Dit is in dit foutscenario niet het geval.
403	5	schoolIdentifier unknown	De Verzender communiceert in de context van een Onderwijsorganisatie die niet bekend is bij Ontvanger
400	99	Vullingsregel: in statusMessage een beschrijving van de reden opnemen	Overige reden

POC Scope

De API specificatie bevat verwijzingen die niet meer actief zijn. Deze gaan in de definitieve versie aangepast worden.