Titel | Notifications API | |||||||||||||||||||||||
Status |
| |||||||||||||||||||||||
Versie | Documentatie: 0.9.1 | |||||||||||||||||||||||
schemaVersion: 0.59.1 | ||||||||||||||||||||||||
Datum12 December 2023 | 27 September 2024 | |||||||||||||||||||||||
Auteur | Architectenraad Edu-V | |||||||||||||||||||||||
Acties |
|
...
| Table of Contents |
|---|
Samenvatting
Scopes |
| Bron |
|
Bron |
| ||
Afnemer |
| ||
BerichtenObjecten | |||
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 Notificatie berichten 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 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.
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 |
| ||||||
schemaVersionnotificationType | stringstring | ENUM | Het versienummer van de berichtdefinitie die wordt gehanteerd. | 1.3.0 | V | Conform Semantic Versioning 2.0.0 | type notificatie zijnde een wijziging van een object of een bulkwijziging |
| V | |||
objectType | string | ENUM | Het type object waarvan een notificatie wordt verstuurd. | Student | V |
| ||||||
objectId | string | string | Identifier van het dataobject dat wordt verstuurd in het Event. | - | O | Is verplicht bij isDeleteEvent | ||||||
userIdTypeschool | stringobject | ENUM | Het type userId dat wordt gehanteerd in het veld objectId, indien het object een user betreft. | ECKiD | 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
...
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
...
edu_org_id 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
| Open api | ||||||
|---|---|---|---|---|---|---|
| ||||||
openapi: 3.0.0
info:
version: 0.0.1
title: Notifications API
description: |-
The Notifications API is implemented by a source of data `Bron` to allow consumers `Afnemers` to receive notifications about new/modified/deleted data objects from the SIS API.
contact:
name: Edu-V
url: www.edu-v.org/afsprakenstelsel
email: info@edu-v.org
components:
schemas:
schemaVersion:
type: string
description: 'Schema version of this object using semantic versioning 2.0.0'
default: 0.0.1
Notification:
type: object
x-tags:
- Notification
description: |-
A notification that something of interest has happened within a service. A subscriber receives notifications within an authorized scope and for certain data objects in the context of a school (using consent). This enables parties to communicate with each other in a loosely coupled way. The event mediator has no direct connection to any of the subscribing systems.
Notifications are sent after a data object is created, modified or deleted. The notification contains the id to this data object and an url to retreive the latest state of the object. The data object is not send as part of the notification itself.
All Notifications have a unique `id`. Moreover, the notification also includes an `objectId`, the identifier of the object they carry. This can be used to make sure notifications are processed in order for that object. The `created` time of the notification is the time the action that triggered the notification happened. It is not the time the notification was sent or processed.
Deleting an object is supported by sending a notification with the field `isDeleteNotification` flagged as true. This indicates that this is the last notification you will get about this object.
title: Notification
properties:
id:
type: string
format: uuid
example: d290f1ee-6c54-4b01-90e6-d701748f0851
description: 'Unique identifier for this Notification.'
schemaVersion:
$ref: '#/components/schemas/schemaVersion'
objectType:
type: string
description: 'The type of object that has changed.'
enum:
- Student
- StudentDelivery
- Employee
- Class
- Group
- SchoolSubject
- SchoolPeriod
- Product
- Course
objectId:
type: string
description: 'Unique identifier of the object sent within this notification.'
userIdType:
type: string
description: 'In case the object is a Student or Employee, this field should be filled with the used userId format in the objectId.'
enum:
- ECKiD
- nlPersonProfileId
- nlPersonRealId
- Las-key
- BasispoortId
- Medewerkernummer
schoolPeriod:
type: string
description: 'In case the oboject is from the SIS API, this field shoudl be filled with the name of the school period for which the data object changed. For example a student could follow a new subject next school year.'
schoolId:
type: string
description: 'In case the object is from the SIS API, this field should be filled with the schoolId of the School for which an entitiy changed. In primary education the BasispoortId is used. In secondary and vocational education the digiDeliveryId is used. The digiDeliveryId is case sensitive.'
edu_org_id:
type: string
description: 'The school needs to approve the exchange of sis data via a consent. The `edu_org_id` parameter is mandatory for these reference components to request entitlement information from the provider. This allows the provider to check if the requesting client has an active data exchange (consent) for the specified edu_org_id.'
created:
type: string
format: date-time
description: |
The moment that the action happened which triggered this notification. As Notifications are sent asynchronous, this is not the moment the Notification was sent.
Format: openapi in ZULU time as specified in RFC 3339, section 5.6
url:
type: string
format: url
description: "The callback url to retreive the modified object."
isDeleteNotification:
type: boolean
description: 'Indication that this is the last notification you will ever see, as the object is deleted.'
required:
- id
- schemaVersion
- objectType
- objectId
- created
NotificationResponse:
type: object
x-tags:
- Notification
description: 'The response for a single Notification given by the Consumer that received the Notification.'
properties:
id:
type: string
description: 'The identifier of the Notification where this response refers to.'
status:
type: integer
description: 'See functional status codes within the Documentation.'
statusMessage:
type: string
description: 'See functional status messages within the Documentation.'
required:
- id
- status
StatusResponse:
title: StatusResponse
type: object
description: 'Functional status code and status message.'
properties:
status:
type: integer
description: 'See functional status codes within the Documentation.'
statusMessage:
type: string
description: 'See functional status messages within the Documentation.'
required:
- status
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.example.com/oauth2/token
refreshUrl: https://api.example.com/oauth2/token
scopes:
catalogue: 'scope that allows Consumers to receive Products from the Catalogue API.'
course: 'scope that allows Consumers to receive Courses from the Course API.'
school: 'a scope that allows a Consumers to receive basic school information: periods and subjects from the SIS API.'
student-employee-group: 'a scope that allows Consumers to receive student, teacher and group data from the SIS API.'
student-delivery: 'a scope that that allows a `Leermiddelenshop` to receive student delivery information including addresses from the SIS API.'
paths:
/subscribe/{api}:
parameters:
- schema:
type: string
enum:
- 'catalogue-api'
- 'sis-api'
- 'course-api'
name: api
in: path
required: true
description: 'API to which the Consumer wants to subscribe.'
post:
summary: 'Subscribe to notifications for new/modified/deleted data objects from an API'
operationId: subscribe
x-tags:
- Notification
tags:
- Producer
description: 'Subscribe to notifications from a specified API. The Producer registers the Consumer as one of the subscribers to changes in the requested API. This includes all data objects for all edu_org_ids for which the Consumer has an active consent with the Producer.'
responses:
'200':
description: OK
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
security:
- OAuth2:
- catalogue
- course
- student-employee-group
- student-delivery
- school
/notification:
parameters:
- schema:
type: string
name: edu_org_id
in: query
required: false
description: "The school needs to approve the exchange of sis data via a consent. The `edu_org_id` parameter is mandatory for these reference components to request entitlement information from the provider. This allows the provider to check if the requesting client has an active data exchange (consent) for the specified edu_org_id."
post:
summary: Receive one notification
operationId: post-notification
x-tags:
- Notification
tags:
- Consumer
description: |
Endpoint to receive a single Notification as a Consumer from different Producers. For example a party with the reference component `Gebruiksomgeving digitaal leermateriaal` can receive notifications from all parties offering `Administratiesysteem onderwijsdeelnemer` reference components.
requestBody:
description: |
The request body contains a single Notification.
Notifications are processed asynchronous. In the request body a status code and message is included as a confirmation if the notifications are received in a correct format. All notifications are confirmed with a status ok (0), excluding notifications that have an invalid format or notifications that were sent in an invalid security scope or consent. See Documentation for functional status codes and messages.
content:
application/json:
schema:
$ref: '#/components/schemas/Notification'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationResponse'
security:
- OAuth2:
- catalogue
- course
- student-employee-group
- student-delivery
- school
/notifications:
parameters:
- schema:
type: string
name: edu_org_id
in: query
required: false
description: "The school needs to approve the exchange of sis data via a consent. The `edu_org_id` parameter is mandatory for these reference components to request entitlement information from the provider. This allows the provider to check if the requesting client has an active data exchange (consent) for the specified edu_org_id."
post:
summary: Receive notifications
operationId: post-notifications
x-tags:
- Notifications
tags:
- Consumer
description: |
Endpoint to receive notifications as a Consumer from different Producers. For example a party with the reference component `Gebruiksomgeving digitaal leermateriaal` can receive notifications from all parties offering `Administratiesysteem onderwijsdeelnemer` reference components.
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Notification'
description: |-
The request body contains a list of Notifications, sorted oldest notifications first. For Notifications that require Consent to be sent and received between parties, Notifications can only be grouped in the same request if they are from the same school.
Notifications are processed asynchronous. In the request body a status code and message is included as a confirmation if the notifications are received in a correct format. All notifications are confirmed with a status ok (0), excluding notifications that have an invalid format or notifications that were sent in an invalid security scope or consent. See Documentation for functional status codes and messages.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NotificationResponse'
'400':
description: Bad Request
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NotificationResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NotificationResponse'
'403':
description: Forbidden
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NotificationResponse'
security:
- OAuth2:
- catalogue
- course
- student-employee-group
- student-delivery
- school
get:
summary: Get notifications after created datetime
operationId: get-notifications-after-created
x-tags:
- Notification
tags:
- Producer
description: |
Allows a subscriber to retrieve a list of past notifications. The provider will not keep the notifications indefinite. This API is available to a party that had downtime and needs to catch up on processing or receiving notifications. The intended retention is a few days to support catching up.
parameters:
- schema:
type: string
in: query
name: createdAfter
description: 'Timestamp to filter on notifications created after a certain moment. Format: openapi in ZULU time as specified in RFC 3339, section 5.6'
- schema:
type: string
enum:
- Student
- StudentDelivery
- Employee
- Class
- Group
- SchoolSubject
- SchoolPeriod
- Product
example: Student
in: query
name: objectType
description: 'Filter by a specific type of object.'
- schema:
type: integer
in: query
name: start
description: 'Start point for pagination of results, defaults to 0'
examples:
default:
value: 0
summary: 'The start point for pagination'
- schema:
type: integer
maximum: 100
in: query
name: limit
description: 'Limit of number of results returned by page, defaults to 20 with max 100.'
examples:
default:
value: 20
summary: 'The default value if none is provided'
max:
value: 100
summary: 'The largest recommended page size'
- schema:
type: string
name: schemaVersion
in: query
required: false
description: 'Optional parameter to request a Notification in a specific schema version. If none supplied, the server will choose its default schema version. This schemaVersion refers to the version of the Nofication format.'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Notification'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
security:
- OAuth2:
- catalogue
- course
- student-employee-group
- student-delivery
- school
x-tags:
- name: Notification |
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.
...
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 | 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
| 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.