Page Comparison

openapi: 3.0.0
info:
  version: 0.0.3
  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 API using semantic versioning 2.0.0.
        The API version number is communicated in the header.
        The major version is communicated in the URI.
        For more information see the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
      default: 0.0.2
    
    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 retrieve 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
          schemaVersiondescription: 'Unique identifier for this Notification.'
  type: string     notificationType:
 description: 'Schema version of this object using semantic versioning 2.0.0'
 type: string
     default: 0.0.2    enum:
     Notification:       type:- object
      x-tags:      - bulk
 - Notification      objectType:
description: |-         Atype: notificationstring
that something of interest has happened within a service. A subscriberdescription: receives'The notificationstype withinof anobject authorizedthat scopehas andchanged.'
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.
enum:
            - Organisation
            - StudyOffering
            - SubjectOffering
  Notifications are sent after a data object is created, modified or- deleted.SchoolPeriod
The notification contains the id to this data object and an url to- retrieveEnrollment
the latest state of the object. The data object is not send as- partAssignment
of the notification itself.         - Group
       All Notifications have a unique `id`.- Moreover,Student
the notification also includes an `objectId`, the identifier of the object they carry.- ThisEmployee
can be used to make sure notifications are processed in order for that- object.Product
The `created` time of the notification is the time the action that triggered- theProductInfo
notification happened. It is not the time the notification was sent or processed.- Course
       Deleting anobjectId:
object is supported by sending a notification with the field `isDeleteNotification`type: flaggedstring
as true. This indicates that this is the last notification youdescription: will'Unique getidentifier aboutof thisthe object. sent within this notification.'
  title: Notification     school:
 properties:         id$ref: '#/components/schemas/SchoolReference'
         typecreated:
string           formattype: uuidstring
          exampleformat: d290f1ee-6c54-4b01-90e6-d701748f0851date-time
          description: 'Unique identifier for this Notification.' |
            The moment that the schemaVersion:action happened which triggered this notification. As Notifications are sent asynchronous, $ref: '#/components/schemas/schemaVersion'
        objectType:this is not the moment the Notification was sent.
            typeFormat: openapi stringin ZULU time as specified in RFC 3339, section 5.6
 description: 'The type of object that has changed.'url:
          enumtype: string
          format: url
- Student         description: "The callback url -to StudentDeliveryretrieve the modified object"
        isDeleteNotification:
- Employee         type: boolean
  - Class       description: 'Indication that this is the -last Groupnotification you will ever see, as the object is deleted.'
   - SchoolSubject  required:
        - id
- SchoolPeriod       - notificationType
    - Product   - objectType
        - created
Course    
    objectIdSchoolReference:
      type: object
  type: string   title: SchoolReference
      description: 'UniqueA identifierreference ofto thea object sent within this notificationSchool organisation.'
        userIdTypeproperties:
          typeorganisationMasterIdentifier: string
          descriptiontype: 'In case the object is a Student or Employee, this field should be filled with the used userId format in the objectId.'string
          description: |
          enum:  The primary identifier for a School. For Schools the `OnderwijsaanbiederId` is -used.
ECKiD            (either -organisationMasterIdentifier nlPersonProfileIdor organisationIds is required)
         - nlPersonRealIdexample: '104A158' # De Mariënborn
        -organisationIds:
Las-key          type: array
 - BasispoortId        description: |
   - Medewerkernummer        A schoolPeriod:secundary identifier for the School. This value is used whenever the type:primary stringidentifier is not available.
       description: 'In case the object is(either fromorganisationMasterIdentifier theor SISorganisationIds API,is thisrequired)
field should be filled with the name of the school perioditems:
for which the data object changed. For example a student could follow atype: newobject
subject next school year.'         schoolIdproperties:
          type:  string  organisationId:
        description: 'In case the object is from the SIStype: API,string
this field should be filled with the schoolId of the School for which an entityorganisationIdType:
changed. In primary education the BasispoortId is used. In secondary and vocational education the digiDeliveryId is used.type: Thestring
digiDeliveryId is case sensitive.'         edu_org_id:    enum:
      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:
- OIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
                  - VE_CODE # Vestigingserkenningcode e.g. 09QQ00 (Marienbornschool)
                  - BP_ID # Basispoort gegenereerde identifier voor de school.
         type: string        - DD_ID # format: date-time
          description: |Door de Centrale Registratie van Edu-iX gegenereerde DigiDeliveryId van de school.
                The moment that- theAS_ID action# happenedDoor whichhet triggeredLeerlingadministratiesysteem thisgegenereerde notification.identifier Asvan Notificationsde areschool.
sent asynchronous, this is not the moment the Notification was sent.  required:
          Format: openapi in ZULU time- asorganisationId
specified in RFC 3339, section 5.6         url:- organisationIdType
    
    typeNotificationResponse:
string      type: object
   format: url  x-tags:
        description:- "TheNotification
callback url to retrieve the modified object."
        isDeleteNotification:
      description: 'The response for a single Notification given by the Consumer that received the Notification.'
   type: boolean  properties:
        descriptionid:
'Indication that this is the last notification you will ever see,type: asstring
the object is deleted.'       requireddescription: 'The identifier of the Notification where this response refers to.'
- id       status:
 - schemaVersion        type: -integer
objectType         - objectIddescription: 'See functional status codes within the Documentation.'
 - created      statusMessage:
   NotificationResponse:       type: string
object       x-tags:   description: 'See functional status messages within -the NotificationDocumentation.'
      descriptionrequired:
'The response for a single Notification given by the- Consumerid
that received the Notification.'     - status
properties:    
    idStatusResponse:
      title: StatusResponse
  type: string   type: object
      description: 'The identifier of the Notification where this response refers to.'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:
         - id- status
    
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
- status         tokenUrl: StatusResponse:https://api.example.com/oauth2/token
      title: StatusResponse   refreshUrl: https://api.example.com/oauth2/token
  type: object       descriptionscopes:
'Functional status code and status message.'       propertiescatalogue: 'scope that allows Consumers to receive Products from status:the Catalogue API.'
        type: integer   course: 'scope that allows Consumers to receive Courses description:from 'Seethe functionalCourse statusAPI.'
codes within the Documentation.'         statusMessageeducation: 'a scope that gives access to all objects from the Education API.'
type: string           descriptionassociation: 'See functional status messages within the Documentation.'a scope that gives access to all objects from the Association API.'
       required     student.basic: 'a scope that gives access to student identifers -and statusname.'
       securitySchemes:     OAuth2student.demographics: 'a scope that gives access to type:student oauth2demographics  attributes.'
    flows:         clientCredentialsstudent.communication: 'a scope that gives access to student communication attributes.'
 tokenUrl: https://api.example.com/oauth2/token           refreshUrl: https://api.example.com/oauth2/token
          scopes:student.accessibility: 'a scope that gives access to student accessibility attributes.'
               cataloguestudent.deliveryaddress: 'a scope that allowsgives Consumersaccess to receivestudent Productsdelivery from the Catalogue APIaddress attributes.'
            courseemployee.basic: 'a scope that allowsgives Consumersaccess to receiveemployee Coursesidentifers from the Course APIand name.'
            schoolemployee.communication: 'a scope that allowsgives aaccess Consumers to receiveemployee basic school information: periods and subjects from the SIS APIcommunication attributes.'
            student-employee-group.roles: 'a scope that allowsgives Consumersaccess to employee receiveorganisation student, teacher and group data from the SIS API.'
roles attributes.'

paths:
  
  /subscribe/{api}:
    parameters:
      student-delivery schema:
   'a scope that that allows a `Leermiddelenshop` totype: receivestring
student delivery information including addresses from the SIS API.'  pathsenum:
     /subscribe/{api}:     parameters:  - 'education-api'
   - schema:        - 'association-api'
 type: string           enum:- 'students-api'
            - 'catalogueemployees-api'
            - 'siscatalogue-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_idsfrom schools 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:
    parameterspost:
      - schemasummary: Receive one notification
       typeoperationId: stringpost-notification
        namex-tags:
edu_org_id        - in:Notification
query      tags:
  required: false     - Consumer
  description: "The school needs todescription: 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."
    postEndpoint 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:
      summary: Receive onedescription: notification|
      operationId: post-notification   The request body contains x-tags:a single Notification.
      - Notification   
   tags:       Notifications are -processed Consumerasynchronous.
      description: |   In the request body a status Endpoint tocode receiveand amessage singleis Notificationincluded as a confirmation Consumerif fromthe differentnotifications Producers.are Forreceived examplein a partycorrect withformat.
the reference component `Gebruiksomgeving digitaal leermateriaal` can receive notifications from allAll partiesnotifications offeringare `Administratiesysteemconfirmed onderwijsdeelnemer`with referencea components.status ok (0), excluding notifications that have requestBody:an invalid format or notifications that were sent in description:an |invalid security scope or consent.
      The request body contains aSee singleDocumentation Notification.for functional status codes and messages.
        content:
       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. application/json:
            schema:
              $ref: '#/components/schemas/Notification'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationNotificationResponse'
      responses:         '200'400':
          description: Bad OKRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '400401':
          description: Bad RequestUnauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '401403':
          description: UnauthorizedForbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
      security:
        - '403'OAuth2:
           description: Forbidden - catalogue
            - course
            - education
            - association
      content:      - student.basic
     application/json:       - student.demographics
      schema:      - student.communication
         $ref: '#/components/schemas/NotificationResponse'  - student.accessability
   security:         - OAuth2:student.deliveryaddress
            - catalogueemployee.basic
            - courseemployee.communicaton
            - student-employee-group.roles
  
  /notifications:
    post:
 - student-delivery    summary: Receive notifications
      operationId: post-notifications
school      /notifications:x-tags:
        - Notifications
parameters:      tags:
- schema:       - Consumer
  type: string   description: |
    name: edu_org_id   Endpoint to receive notifications as a in:Consumer queryfrom different Producers.
      required: false For example a party with the reference component description:`Gebruiksomgeving "Thedigitaal schoolleermateriaal` needscan toreceive approvenotifications thefrom exchangeall ofparties sisoffering data`Administratiesysteem viaonderwijsdeelnemer` areference consentcomponents.
The `edu_org_id` parameter is mandatory for these referencerequestBody:
components to request entitlement information from the provider. Thiscontent:
allows the provider to check if the requesting client has anapplication/json:
active data exchange (consent) for the specified edu_org_id."     postschema:

     summary: Receive notifications       operationIdtype: array
post-notifications       x-tags:       items:
 - Notifications       tags:       $ref:  - Consumer'#/components/schemas/Notification'
        description: |-
        Endpoint  toThe receiverequest notificationsbody ascontains 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: 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.
          
content:          Notifications application/json:are processed asynchronous.
          schema:In the request body a status code and message is included as a confirmation if type:the arraynotifications are received in a correct format.
        items:  All notifications are confirmed with a status ok (0), excluding notifications that have an invalid $ref: '#/components/schemas/Notification'
        description: |-
format or notifications that were sent in an invalid security scope or consent.
         The requestSee bodyDocumentation containsfor afunctional liststatus ofcodes Notifications,and sortedmessages.
oldest notifications first. For Notifications that requireresponses:
Consent to be sent and received between parties, Notifications can only be grouped in the same request if they are from the same school. '200':
          description: OK
          content:
            application/json:
Notifications are processed asynchronous. In the request body a status code and message is includedschema:
as a confirmation if the notifications are received in a correct format. All notifications are confirmed withtype: aarray
status ok (0), excluding notifications that have an invalid format or notifications that were sent in anitems:
invalid security scope or consent. See Documentation for functional status codes and messages.       responses:$ref: '#/components/schemas/NotificationResponse'
        '200400':
          description: OKBad Request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationResponse'
        '400401':
          description: Bad RequestUnauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationResponse'
        '401403':
          description: UnauthorizedForbidden
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationResponse'
        '403'security:
        -  descriptionOAuth2: Forbidden
          content:  - catalogue
         application/json:   - course
          schema:  - education
            - type:association
array            - student.basic
   items:                   $ref: '#/components/schemas/NotificationResponse'
      
      
  - student.demographics
   security:         - OAuth2:student.communication
            - cataloguestudent.accessability
            - coursestudent.deliveryaddress
            - student-employee-group.basic
            - student-deliveryemployee.communicaton
            - schoolemployee.roles
            
    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: createdAftersince
          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:    summary: 'The largest recommended page size'
   type: string  responses:
        name'200':
schemaVersion           indescription: queryOK
          requiredcontent:
 false           descriptionapplication/json:
'Optional parameter to request a Notification in a specific schema version. If none supplied, theschema:
server will choose its default schema version. This schemaVersion refers to the version of the Notification format.'type: array
     responses:         '200':  items:
        description: OK         $ref:  content:'#/components/schemas/Notification'
        '400':
    application/json:      description: Bad Request
      schema:    content:
            typeapplication/json:
array                 itemsschema:

                 $ref: '#/components/schemas/NotificationStatusResponse'
        '400401':
          description: Bad RequestUnauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401403':
          description: UnauthorizedForbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      security:
        - '403':OAuth2:
             description: Forbidden- catalogue
            - course
    content:        - education
   application/json:         - association
    schema:        - student.basic
       $ref: '#/components/schemas/StatusResponse'    - student.demographics
 security:           - OAuth2:student.communication
            - cataloguestudent.accessability
            - coursestudent.deliveryaddress
            - student-employee-group.basic
            - student-deliveryemployee.communicaton
            - school
  employee.roles
x-tags:
  - name: Notification