Notifications API

Titel

Notifications API

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer

Versie

Documentatie: 0.0.9

schemaVersion: 0.0.4

Datum

19 April 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

  • Administratiesysteem onderwijsmedewerker

Afnemer

  • Selectieomgeving leermiddelen

  • Bestelomgeving leermiddelen

  • Aanspraakmanager

  • Distributiefaciliteit

  • Licentieregistratie

  • Gebruiksomgeving digitaal leermateriaal

  • Digitaal toetssyteem

  • Leermiddelenportaal

  • Onderwijsleeromgeving

  • Leermiddelendashboard

Objecten

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

Object: Notification

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

Bij het versturen van Notificatie objecten 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.

  • 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.

  • 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.

  • 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 type notificatie zijnde een wijziging van een object of een bulkwijziging

object

bulk

V

 

objectType

string

ENUM

Het type object waarvan een notificatie wordt verstuurd.

Organisation
StudyOffering
SubjectOffering
SchoolPeriod
Enrollment
Assignment
Group
Student
Employee
Product
ProductInfo
Course

V

 

objectId

string

string

Identifier van het dataobject dat wordt verstuurd in het Event.

-

O

Is verplicht bij isDeleteEvent

school

object

schoolreference

Referentie naar de identifier van de onderwijsaanbieder waarvoor consent is geregistreerd.

Zie referentie naar school

O

Verplicht zodra het een notificatie betreft over de:

  • Education API

  • Association API

  • Students API

  • Employees API

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: 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.