Page Comparison

openapi: 3.0.0
info:
  title: Notifications API
  version: 0.9.0.4
  
  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.0.4
    
    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:
            catalogue: 'scope that allows Consumers to receive Products from the Catalogue API.'
            course: 'scope that allows Consumers to receive Courses from the Course API.'
            education: 'a scope that gives access to all objects from the Education API.'
            association: 'a scope that gives access to all objects from the Association API.'
            student.basic: 'a scope that gives access to student identifiers and name.'
            student.demographics: 'a scope that gives access to student demographics attributes.'
            student.communication: 'a scope that gives access to student communication attributes.'
            student.accessibility: 'a scope that gives access to student accessibility attributes.'
            student.deliveryaddress: 'a scope that gives access to student delivery address attributes.'
            employee.basic: 'a scope that gives access to employee identifiers and name.'
            employee.communication: 'a scope that gives access to employee communication attributes.'
            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:
            - catalogue
            - course
            - student-employee-group
            - student-delivery
            - school
  
  
  /notification:
    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
            - education
            - association
            - student.basic
            - student.demographics
            - student.communication
            - student.accessability
            - student.deliveryaddress
            - employee.basic
            - employee.communication
            - employee.roles
  
  /notifications:
    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
            - education
            - association
            - student.basic
            - student.demographics
            - student.communication
            - student.accessability
            - student.deliveryaddress
            - employee.basic
            - employee.communication
            - employee.roles
            
    get:
      summary: Get notifications
      operationId: get-notifications
      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: since
          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'
      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
            - education
            - association
            - student.basic
            - student.demographics
            - student.communication
            - student.accessability
            - student.deliveryaddress
            - employee.basic
            - employee.communication
            - employee.roles
x-tags:
  - name: Notification