Page Comparison

openapi: 3.0.0
info:
  title: Notifications API
  version: 0.9.01
  
  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.9.01
    
    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
          description: 'Unique identifier for this Notification.'
        notificationType:
          type: string
          enum:
            - object
            - bulk
        objectType:
          type: string
          description: 'The type of object that has changed.'
          enum:
            - Organisation
            - StudyOffering
            - SubjectOffering
            - SchoolPeriod
            - Enrollment
            - Assignment
            - Group
            - Student
            - Employee
            - Product
            - ProductInfo
            - Course
        objectId:
          type: string
          description: 'Unique identifier of the object sent within this notification.'
        school:
          $ref: '#/components/schemas/SchoolReference'
        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 retrieve 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
        - notificationType
        - objectType
        - created
    
    SchoolReference:
      type: object
      title: SchoolReference
      description: 'A reference to a School organisation.'
      properties:
        organisationMasterIdentifier:
          type: string
          description: |
            The primary identifier for a School. For Schools the `OnderwijsaanbiederId` is used.
            (either organisationMasterIdentifier or organisationIds is required)
          example: '104A158' # De Mariënborn
        organisationIds:
          type: array
          description: |
            A secondary identifier for the School. This value is used whenever the primary identifier is not available.
            (either organisationMasterIdentifier or organisationIds is required)
          items:
            type: object
            properties:
              organisationId:
                type: string
              organisationIdType:
                type: string
                enum:
                  - OIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
                  - VE_CODE # Vestigingserkenningcode e.g. 09QQ00 (Marienbornschool)
                  - BP_ID # Basispoort gegenereerde identifier voor de school.
                  - DD_ID # Door de Centrale Registratie van Edu-iX gegenereerde DigiDeliveryId van de school.
                  - AS_ID # Door het Leerlingadministratiesysteem gegenereerde identifier van de school.
            required:
              - organisationId
              - organisationIdType
    
    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:
            eduv.catalogue: 'scope that allows Consumers to receive Products from the Catalogue API.'
            eduv.course: 'scope that allows Consumers to receive Courses from the Course API.'
            eduv.education: 'a scope that gives access to all objects from the Education API.'
            eduv.association: 'a scope that gives access to all objects from the Association API.'
            eduv.student.basic: 'a scope that gives access to student identifiers and name.'
            eduv.student.demographics: 'a scope that gives access to student demographics attributes.'
            eduv.student.communication: 'a scope that gives access to student communication attributes.'
            eduv.student.accessibility: 'a scope that gives access to student accessibility attributes.'
            eduv.student.deliveryaddress: 'a scope that gives access to student delivery address attributes.'
            eduv.employee.basic: 'a scope that gives access to employee identifiers and name.'
            eduv.employee.communication: 'a scope that gives access to employee communication attributes.'
            eduv.employee.roles: 'a scope that gives access to employee organisation roles attributes.'

paths:
  
  /subscribe/{api}:
    parameters:
      - schema:
          type: string
          enum:
            - 'education-api'
            - 'association-api'
            - 'students-api'
            - 'employees-api'
            - 'catalogue-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 from 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:
            - eduv.catalogue
            - eduv.course
            - student-employee-groupeduv.education
            - student-deliveryeduv.association
            - eduv.student.basic
 school         /notification:  - eduv.student.demographics
 post:       summary: Receive one notification - eduv.student.communication
    operationId: post-notification       x-tags: eduv.student.accessibility
       - Notification    - eduv.student.deliveryaddress
  tags:          - Consumereduv.employee.basic
      description: |     - eduv.employee.communication
  Endpoint to receive a single Notification as a Consumer from different- Producerseduv.employee.roles
For  
example a party
with the reference/notification:
component `Gebruiksomgeving digitaal leermateriaal` canpost:
receive notifications from all parties offering `Administratiesysteemsummary: onderwijsdeelnemer`Receive referenceone components.notification
      requestBodyoperationId: post-notification
       descriptionx-tags:
|        - Notification
 The request body contains a singletags:
Notification.        - Consumer
      description: |
    Notifications are processed asynchronous. Endpoint to receive a single Notification as a Consumer from Indifferent theProducers. requestFor bodyexample a statusparty codewith andthe messagereference iscomponent included`Gebruiksomgeving asdigitaal aleermateriaal` confirmationcan ifreceive the notifications arefrom receivedall inparties aoffering correct`Administratiesysteem format.onderwijsdeelnemer` reference components.
      requestBody:
 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 consentdescription: |
          The request body contains a single Notification.
          See
Documentation for functional status codes and messages.    Notifications are processed asynchronous.
 content:         In the application/json:request body a status code and message is included as a confirmation if schema:the notifications are received in a correct format.
       $ref: '#/components/schemas/Notification'  All notifications are confirmed with responses:a status ok (0), excluding notifications that have an '200':invalid format or notifications that were sent in an invalid security description:scope OKor consent.
         content: See Documentation for functional status codes and messages.
    application/json:    content:
          schemaapplication/json:
            schema:
    $ref:           $ref: '#/components/schemas/NotificationResponse'Notification'
      responses:
        '400200':
          description: Bad RequestOK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '401400':
          description: UnauthorizedBad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '403401':
          description: ForbiddenUnauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        security'403':
        -  OAuth2description: Forbidden
          content:
- catalogue           application/json:
 -  course           schema:
 -   education             - association$ref: '#/components/schemas/NotificationResponse'
      security:
        - student.basicOAuth2:
            - studenteduv.demographicscatalogue
            - studenteduv.communicationcourse
            - studenteduv.accessabilityeducation
            - studenteduv.deliveryaddressassociation
            - employeeeduv.student.basic
            - employeeeduv.student.communicationdemographics
            - employee.roles
  eduv.student.communication
  /notifications:     post:       summary: Receive notifications
      operationId: post-notifications eduv.student.accessibility
     x-tags:
        - Notifications
  eduv.student.deliveryaddress
   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.
    eduv.employee.basic
            - eduv.employee.communication
     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.
- eduv.employee.roles
  
  /notifications:
    post:
      summary: Receive notifications
      operationId: post-notifications
 See Documentation for functional status codesx-tags:
and messages.       responses:- Notifications
      tags:
'200':        - Consumer
 description: OK    description: |
     content:   Endpoint to receive notifications as a Consumer from different Producers.
application/json:        For example a party with the reference schema:component `Gebruiksomgeving digitaal leermateriaal` can receive notifications from all parties offering `Administratiesysteem onderwijsdeelnemer` reference components.
  type: array   requestBody:
        content:
    items:      application/json:
            $refschema:
'#/components/schemas/NotificationResponse'          '400':    type: array
     description: Bad Request       items:
   content:             application/json$ref: '#/components/schemas/Notification'
         description: |-
  schema:        The request body contains a list of Notifications, sorted type:oldest arraynotifications first. For Notifications that require Consent to be sent and received between parties, Notifications can only items:be grouped in the same request if they are from the same school.
      $ref: '#/components/schemas/NotificationResponse'   
     '401':     Notifications are processed asynchronous.
  description: Unauthorized       In the request body content:a status code and message is included as a confirmation if the  application/json:notifications are received in a correct format.
        schema:  All notifications are confirmed with a status ok (0), excluding notifications that have an invalid type:format arrayor notifications that were sent in an invalid security scope or consent.
     items:     See Documentation for functional status codes and messages.
      $refresponses:
'#/components/schemas/NotificationResponse'         '403200':
          description: ForbiddenOK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationResponse'
       security: '400':
          description: Bad Request
         - OAuth2content:
            -application/json:
catalogue             - courseschema:
            - education   type: array
        - association       items:
     - student.basic             - student.demographics$ref: '#/components/schemas/NotificationResponse'
        '401':
    - student.communication     description: Unauthorized
      - student.accessability   content:
         - student.deliveryaddress  application/json:
          - employee.basic   schema:
         - employee.communication      type: array
     - employee.roles          items:
       get:       summary: Get notifications  $ref: '#/components/schemas/NotificationResponse'
   operationId: get-notifications    '403':
  x-tags:        description: -Forbidden
Notification       tags:   content:
     - Producer       descriptionapplication/json:
|         Allows a subscriber to retrieve aschema:
list of past notifications.         The provider will not keeptype: thearray
notifications indefinite.         This API is available to a partyitems:
that had downtime and needs to catch up on processing or receiving notifications.         The intended retention is a few days to support catching up.$ref: '#/components/schemas/NotificationResponse'
      security:
        -  parametersOAuth2:
        - schema:   - eduv.catalogue
         type: string  - eduv.course
       in: query    - eduv.education
     name: since      - eduv.association
   description: 'Timestamp to filter on notifications created after a certain- momenteduv.student.basic
Format:   openapi in ZULU time as specified in RFC 3339, section- 5.6'eduv.student.demographics
            - schema: eduv.student.communication
             type: string- eduv.student.accessibility
             enum:- eduv.student.deliveryaddress
            - Studenteduv.employee.basic
            - StudentDeliveryeduv.employee.communication
            - eduv.employee.roles
Employee            
- Class   get:
      summary: Get notifications
- Group     operationId: get-notifications
      x-tags:
SchoolSubject        - Notification
   - SchoolPeriod  tags:
          - ProductProducer
            exampledescription: Student|
        Allows a in:subscriber queryto retrieve a list of past notifications.
    name: objectType   The provider will not keep the   description: 'Filter by a specific type of object.'notifications indefinite.
        This API is available to a -party schema:that had downtime and needs to catch up on processing or receiving notifications.
type: integer       The intended retention is in:a queryfew days to support catching up.
     name parameters:
start        - schema:
 description: 'Start point for pagination of results, defaults to 0'  type: string
       examples:   in: query
        default:  name: since
          description: value:'Timestamp 0to filter on notifications created after a certain moment. Format: openapi in ZULU time as summary:specified 'Thein startRFC point3339, forsection pagination5.6'
        - schema:
            type: integerstring
            maximumenum:
100            - Student
  in:  query        - StudentDelivery
 name: limit          - description:Employee
'Limit of number of results returned by page, defaults to 20 with max- 100.'Class
          examples:  - Group
         default:   - SchoolSubject
          value: 20 - SchoolPeriod
            summary:- 'TheProduct
default value if none is provided'       example: Student
    max:      in: query
       value: 100  name: objectType
           summarydescription: 'The largest recommended page sizeFilter by a specific type of object.'
      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:
            - eduv.catalogue
            - eduv.course
            - eduv.education
            - eduv.association
            - eduv.student.basic
            - eduv.student.demographics
            - eduv.student.communication
            - eduv.student.accessabilityaccessibility
            - eduv.student.deliveryaddress
            - eduv.employee.basic
            - eduv.employee.communication
            - eduv.employee.roles
x-tags:
  - name: Notification