Titel |
Notifications API | ||||
Status |
|
|
|
|
|
| title | CONCEPT |
|---|
Stadium
|
|
| Status | ||
|---|---|---|
|
|
| ||
Versie | Documentatie: 0.9.1 | |
schemaVersion: 0.9.1 | ||
Datum |
27 September 2024 | |
Auteur | Architectenraad Edu-V |
Acties |
|
De
...
Notifications API is
...
Endpoint abonneeservice toevoegen conform het transactiepatroon van Edukoppeling.
...
Toevoegen van veld SchoolIdentifier aan Event ter validatie van (de)activering gegevensuitwisseling op Resource server?
De Events API is de technische implementatie van het transactiepatroon Abonneren op wijzigen middels notificaties en Georkestreerde uitwisseling.
De technische de technische implementatie van het transactiepatroon Abonneren op wijzigen middels notificaties.
De technische specificatie bestaat uit:
| Table of Contents |
|---|
Samenvatting
Scopes |
|
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
Berichtdefinitie: Event
...
| |
Bron |
|
Afnemer |
|
Objecten | |
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 |
| Anchor | ||||
|---|---|---|---|---|
|
Een Notificatie bevat alle informatie ten behoeve van de berichteninfrastructuur om deze als Leverancier correct te kunnen verwerken.
Bij het versturen van Event berichten Notificatie objecten 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 Zodra er meerdere Notificaties tegelijkertijd worden verstuurd dan zijn ze gesorteerd op volgorde van aanmaken (veld created), de oudste events notificaties als eerste.
In het Ecosysteem worden Events Er is onderscheid gemaakt in een Notificatie voor een wijziging van een object en een bulkwijziging.
Notificaties worden gestuurd na een gebeurtenis:
Voor een object: en het aanmaken van een dataobject (bijvoorbeeld een nieuwe, gewijzigde of verwijderde entiteit)
.
Voor een bulk: er heeft een bulkwijziging plaatsgevonden. Een voorbeeld van een bulkwijziging is de import van gegevens.
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 het eventde notificatie. Deze tijdstempel betreft niet het moment van versturen of verwerken van het eventde notificatie. Dit veld kan door de Ontvanger gebruikt worden om berichten notificaties op volgorde te verwerken.
Voor het verwijderen van een dataobject kan door de Verzender gebruik gemaakt worden van het veld isDeleteEvent isDeleteNotification 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 notificaties meer verstuurd worden voor dit dataobject.
Alle Notificaties dienen te worden verwerkt door de ontvanger.
Veld | Type | Format | Omschrijving | Voorbeeld | O/V | Vullingsregel |
id | string | uuid | Unieke identifier voor |
deze notificatie | d290f1ee-6c54-4b01-90e6-d701748f0851 | V |
|
notificationType | string |
ENUM | Het |
1.3.0
V
Conform Semantic Versioning 2.0.0
type
type notificatie zijnde een wijziging van een object of een bulkwijziging |
| V | |
objectType | string | ENUM | Het type |
object waarvan een notificatie wordt verstuurd. |
| 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*
school | object | schoolreference | Referentie naar de identifier van de onderwijsaanbieder waarvoor consent is geregistreerd. | O | Verplicht zodra het een notificatie betreft over de:
| |
created | string | datetime | Tijdstempel van actie die als trigger heeft gediend voor |
de notificatie | 2017-07-21T17:32:28Z | V |
|
url |
isDeleteEvent
string |
-
Het dataobject dat conform de bijbehorende berichtdefinitie wordt verstuurd.
-
O
Kan leeg blijven bij isDeleteEvent
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
...
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
Technisch: API specificatie
POC Scope
De API specificatie bevat verwijzingen die niet meer actief zijn. Deze gaan in de definitieve versie aangepast worden.
...
| filter | none |
|---|---|
| supportedSubmitMethods | none |
| showDownloadButton | true |
...
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
| Open api | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
...
Release notes
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.
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.
0.0.8: Typo’s verwijderd uit de YAML file.
0.0.9: De volgende wijzigingen zijn doorgevoerd:
De bulkwijziging is toegevoegd.
De wijzigingen in de architectuur zijn doorgevoerd waardoor het edu_org_id en de schemaVersion is gewijzigd.
De informatieobjecten zijn bijgewerkt op basis van de laatste wijzigingen in de specificaties.
0.9.0: Het Architectuurkader Edu-V is vastgesteld als startpunt voor de implementatie. Tevens is instemming verleend op verdere doorontwikkeling van het Architectuurkader Edu-V op basis van de Architectuurprincipes. Dit akkoord is verleend op het Bestuurlijk Overleg van 27 mei 2024.
De afspraken m.b.t. het Verzenden en ontvangen van berichten wordt tijdens een toekomstige release geïmplementeerd. Na een succesvolle implementatie wordt de uiteindelijke 1.0.0 versie vastgesteld.
0.9.1: 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.