Usage Prototype

openapi: 3.0.0
info:
  title: Usage API
  version: '1.0.0'
  description: |
    The Usage API is implemented by the `Licentieregistratie` and `Aanspraakmanager`.
    The Usage API is used to report InitialActivations of digital learning materials to the `Aanspraakmanager`.
    
    InitialActivation information is being send via the message-confirmation transaction pattern.
    Therefore the consuming reference component `Aanspraakmanager` needs to implement endpoints to receive usage data.
    
    The `Licentieregistratie` is the source of Usage information and provides GET endpoints to the `Aanspraakmanager` and `Bestelomgeving leermiddelen` for support and billing reasons.
    Moreover, the `Leermiddelendashboard` is able to request Usage information for a school or a student at a school.
  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: 1.0.0
    
    InitialActivation:
      title: InitialActivation
      type: object
      x-tags:
        - InitialActivation
      description: |
        The message a `Licentieregistratie` sends to the `Aanspraakmanager` after a Student or Employee activates (and first uses) a Product.
        The Student or Employee exercises his right to activate the Product and the entitlement is licensed for the Product.
      properties:
        entitlementId:
          type: string
          format: uuid
          description: 'The Entitlement which included the right of the Student or Employee to activate the Product.'
        productId:
          type: string
          description: 'Refers to a (bundled) product on the Entitlement.'
        entitlementType:
          type: string
          description: |
            The entitlement type specifies if a student, employee or a user with an activation code can activate and license the product.
          enum:
            - school-student
            - school-employee
            - school-activationcode
            - customer-student
            - customer-activationcode
        school:
          $ref: '#/components/schemas/SchoolReference'
        user:
          $ref: '#/components/schemas/UserReference'
        activationCode:
          type: string
          description: 'In case the Product has been activated by an activation code, the `Licentieregistratie` reports here that the activation code is being issued.'
        usageDate:
          type: string
          format: date
          description: 'The date the Product has been activated. Format: YYYY-MM-DD (according to RFC3339).'
        usageType:
          type: string
          default: initial-activation
          description: 'Within the InitialActivation message this value is always initial-activation'
          enum:
            - initial-activation
            - unique-usage
            - weekly-usage
            - monthly-usage
        expirationDate:
          type: string
          format: date
          description: |
            The expiration date until this Student or Employee has the right to use the Product. Format: YYYY-MM-DD (according to RFC3339).
            In case the Entitlement specified a minExpirationDate, the expirationDate equals this minExpirationDate or lies further in the future.
            The expirationDate allows the `Licentieregistratie` to have license periods for each individual License on an Entitlement.
      required:
        - entitlementId
        - productId
        - entitlementType
        - user
        - usageDate
        - usageType
        - expirationDate
    
    DeliveryOrderUsage:
      title: DeliveryOrderUsage
      type: object
      x-tags:
        - Usage
      description: |
        This object reports all Usage information for a single DeliveryOrder.
        Status information from the Entitlement is added to create a reporting overview of quantities entitled, licensed, and used.
      properties:
        deliveryOrderId:
          type: string
          format: uuid
          description: 'The deliveryOrderId which was part of the DeliveryOrder request send by the `Bestelomgeving leermiddelen` to the `Aanspraakmanager` and from the `Aanspraakmanager to the Licentieregistratie.'
        totalEntitled:
          type: integer
          description: 'Total number of entitlements that are entitled to users.'
        totalLicensed:
          type: integer
          description: 'Total number of entitlements that are licensed to users.'
        totalCancelled:
          type: integer
          description: 'Total number of entitlements that are cancelled for users.'
        totalBlocked:
          type: integer
          description: 'Total number of entitlements that are blocked for users.'
        totalExpired:
          type: integer
          description: 'Total number of entitlements that are expired for users.'
        entitlements:
          type: array
          description: |
            The entitlements which are registered on the Contract.
            For each `licensed` entitlement, the `Licentieregistratie` has send an InitialActivation event.'
          items:
            $ref: '#/components/schemas/EntitlementUsage'
      required:
        - deliveryOrderId
        - entitlements

    SchoolUserUsage:
      title: SchoolUserUsage
      type: object
      x-tags:
        - Usage
      description: |
        This object reports all Usage information from a single Student or Employee from a School.
      properties:
        school:
          $ref: '#/components/schemas/SchoolReference'
        user:
          $ref: '#/components/schemas/UserReference'
        totalEntitled:
          type: integer
          description: 'Total number of entitlements that are entitled for this user.'
        totalLicensed:
          type: integer
          description: 'Total number of entitlements that are licensed for this users.'
        totalCancelled:
          type: integer
          description: 'Total number of entitlements that are cancelled for this users.'
        totalBlocked:
          type: integer
          description: 'Total number of entitlements that are blocked for this users.'
        totalExpired:
          type: integer
          description: 'Total number of entitlements that are expired for this users.'
        entitlements:
          type: array
          description: 'An array of all entitlements for the Student or Employee.'
          items:
            $ref: '#/components/schemas/EntitlementUsage'
      required:
        - school
        - user
        - entitlements

    EntitlementUsage:
      title: EntitlementUsage
      type: object
      x-tags:
        - Usage
      description: |
        This object reports all Usage information from a single Entitlement.
        Moreover, information from the Entitlement is added to create a reporting overview of quantities entitled, licensesd and active usage.
      properties:
        entitlementId:
          type: string
          format: uuid
          description: 'The identifier of the Entitlement.'
        productId:
          type: string
          description: 'Refers to a (bundled) product from the Entitlement.'
        entitlementType:
          type: string
          description: |
            The entitlement type specifies if a student, employee or a user with an activation code can activate and license the product.
          enum:
            - school-student
            - school-employee
            - school-activationcode
            - customer-student
            - customer-activationcode
        entitlementStatus:
          type: string
          description: 'The status of the Entitlement as registered by the `Licentieregistratie`.'
          enum:
            - entitled
            - licensed
            - cancelled
            - blocked
        school:
          description: 'This value is mandatory if the entitlementType is school-student, school-employee or school-activationcode'
          $ref: '#/components/schemas/SchoolReference'
        user:
          description: 'This value is mandatory if the entitlementType is school-student, school-employee or customer-student'
          $ref: '#/components/schemas/UserReference'
        activationCode:
          type: string
          description: |
            This value is mandatory if the entitlementType is school-activationcode or customer-activationcode. 

            The activation code as send by the `Aanspraakmanager` as part of the entitlement.
            In case the entitlementStatus is Licensed, the product is activated with the activation code. It is not able to use the activation code again.
        expirationDate:
          type: string
          format: date
          description: 'The expiration date of this entitlement. Format: YYYY-MM-DD (according to RFC3339).'
        usage:
          $ref: '#/components/schemas/usage'
      required:
        - entitlementId
        - entitlementType
        - entitlementStatus
    
    usage:
      title: usage
      type: object
      x-tags:
        - Usage
      properties:
        firstUsed:
          type: string
          format: date
          description: |
            The date the Product has been activated (and first used) by the Student or Employee. Format: YYYY-MM-DD (according to RFC3339).
            
            This date has been reported by the `Licentieregistratie` in the InitialActivation event.'
        lastUsed:
          type: string
          format: date
          description: |
            The date the Product has last been used by the Student or Employee. Format: YYYY-MM-DD (according to RFC3339). This information is only exchanged within the scope of usage.usage.
        frequencyOfUsage:
          type: integer
          description: |
            Indicator how often the Student or Employee has used the Product (count at moment of login).
            
            This information is optional and only exchanged within the scope of usage.usage.
      required:
        - firstUsed
    
    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)
                  - 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

    UserReference:
      type: object
      title: UserReference
      properties:
        userMasterIdentifier:
          type: string
          description: |
            The primary identifier for a User.
            For Students the ECK iD is used.
            For Employees this value is empty. There is no primary identifier for Employees.
            (either userMasterIdentifier or userIds is required)
        userIds:
          type: array
          description: |
            A secondary identifier for a User. This value is used whenever the primary identifier is not available.
            For Employees this value is mandatory.
            (either userMasterIdentifier or userIds is required)
          items:
            type: object
            properties:
              userId:
                type: string
              userIdType:
                type: string
                enum:
                  - NEPPI # nlPersonProfileId – value can be used for students and employees
                  - BPI # Basispoort ID – value can be used for students and employees
                  - eduID # eduID identifier – value can be used for students and employees
                  - NEPRI # nlPersonRealId – value can be used for students only
                  - ASI # Las-key – value can be used for students only
                  - eckId # ECK iD – value can be used for employees only, eckId is userIdType for userMasterIdentifier for students
            required:
              - userId
              - userIdType
    
    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.usage.seller: 'scope that allows a `Bestelomgeving leermiddelen` request usage information for billing and/or support.'
            eduv.usage.entitlor: 'scope that allows an `Aanspraakmanager` to receive InitialActivation messages and to request usage information about entitlements and/or deliveryOrders.'
            eduv.usage.dashboard: 'scope that allows a `Leermiddelendashboard` to request usage information.'
      description: ''
paths:

  # GET endpoint for support processes of all parties involved, therefore applicable to all reference components.

  /usage/entitlements/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    get:
      summary: Get Usage by Entitlement
      operationId: get-usage-by-entitlement
      tags:
        - Licentieregistratie
      x-tags:
        - InitialActivation
        - Usage
        - Entitlement
      description: |
        Retrieve all Usage information from a single Entitlement.
        Moreover, information from the Entitlement is added to create a reporting overview of quantities entitled, licensed, and used.
        
        This information was already send to the `Aanspraakmanager` within InitialActivation messages.
        This endpoint is available for support reasons and allows these reference components to gather status information on an Entitlement from the `Licentieregistratie`.

        This endpoint is available for the `Bestelomgeving leermiddelen` and the `Aanspraakmanager`. No consent is required to receive the information.
        
        The `Licentieregistratie` is the provider of this endpoint.
        The `Aanspraakmanager` should give a 405 HTTP status as result when called.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementUsage'
        '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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method not allowed - Licentieregistratie is provider of this endpoint
      security:
        - OAuth2:
            - eduv.usage.seller
            - eduv.usage.entitlor
            - eduv.usage.dashboard

  /usage/deliveryorders/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: 'The deliveryOrderId for which usage information is requested.'
    get:
      summary: Get Usage by DeliverOrder
      operationId: get-usage-by-deliveryorder
      tags:
        - Licentieregistratie
      x-tags:
        - InitialActivation
        - Usage
        - Entitlement
        - DeliveryOrder
      description: |
        Retrieve all Usage information from a single DeliveryOrder.
        Moreover, information from the DeliveryOrders and Entitlements is added to create a reporting overview of quantities entitled, licensed, and used.        
        
        This endpoint is available for the `Bestelomgeving leermiddelen` and the `Aanspraakmanager`. No consent is required to receive the information.
        Consent is required for exchange of usage information from the 'Licentieregistratie' to the `Leermiddelendashboard`.

        The `Licentieregistratie` is the provider of this endpoint.
        The `Aanspraakmanager` should give a 405 HTTP status as result when called.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryOrderUsage'
        '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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method not allowed - Licentieregistratie is provider of this endpoint
      security:
        - OAuth2:
            - eduv.usage.seller
            - eduv.usage.entitlor
            - eduv.usage.dashboard
  
  # GET endpoints for `Leermiddelendashboard`

  /usage/school:
    parameters:
      - schema:
          type: string
        name: orgMasterId
        in: query
        required: false
        description: |
          The organisationMasterIdentifier of the school.
          This parameter is used when the primary identifier for a school (being the `OnderwijsaanbiederId`) is available.
      - schema:
          type: string
        name: orgId
        in: query
        required: false
        description: |
          The organisationIdentifier (secondary identifier) of the school.
          This parameter is used in combination with the orgIdType when the organisationMasterIdentifier is not available.
      - schema:
          type: string
          example: DD_ID
          enum:
            - OIE_CODE
            - BP_ID
            - DD_ID
            - AS_ID
        name: orgIdType
        in: query
        required: false
        description: |
          The type of the organisationIdentifier.
          This parameter is used in combination with the orgId when the organisationMasterIdentifier is not available.
    get:
      summary: Get Usage for School
      operationId: get-usage-for-school
      tags:
        - Licentieregistratie
      x-tags:
        - InitialActivation
        - Usage
        - Entitlement
        - DeliveryOrder
      description: |
        Retrieve all Usage information from a single School.
        Moreover, information from the DeliveryOrders and Entitlements is added to create a reporting overview of quantities entitled, licensed, and used.
        
        This endpoint is available for the `Leermiddelendashboard`. Consent is required for exchange of usage information from the 'Licentieregistratie' to the `Leermiddelendashboard`.

        The `Licentieregistratie` is the provider of this endpoint.
        The `Aanspraakmanager` should give a 405 HTTP status as result when called.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryOrderUsage'
        '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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method not allowed - Licentieregistratie is provider of this endpoint
      security:
        - OAuth2:
            - eduv.usage.dashboard

  /usage/school/user:
    post:
      summary: Get Usage for User at School
      operationId: get-usage-for-user-at-school
      tags:
        - Licentieregistratie
      x-tags:
        - InitialActivation
        - Usage
        - Entitlement
      description: |
        Retrieve all Usage information from a single Student or Employee at a school.
        This information was already send to the `Aanspraakmanager` within InitialActivation messages.
        This endpoint is available for support reasons and allows these reference components to gather status information for all entitlements of a single Student or Employee from the `Licentieregistratie`.
        
        The `Licentieregistratie` is the provider of this endpoint.
        The `Aanspraakmanager` should give a 405 HTTP status as result when called.
        Consent is required for exchange of usage information from the 'Licentieregistratie' to the `Leermiddelendashboard`.
        
        Due to the confidentiality of the eckId and userIds this endpoint has been implemented as a POST endpoint where the confidential information is securely send within the request body.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                school:
                  $ref: '#/components/schemas/SchoolReference'
                user:
                  $ref: '#/components/schemas/UserReference'
              required:
                - school
                - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SchoolUserUsage'
        '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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method not allowed - Licentieregistratie is provider of this endpoint
      security:
        - OAuth2:
            - eduv.usage.dashboard

  # GET endpoints for `Bestelomgeving leermiddelen` en `Aanspraakmanager`

  /usage/contracts/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: 'The contractId for which usage information is requested.'
    get:
      summary: Get Usage by Contract
      operationId: get-usage-by-contract
      tags:
        - Licentieregistratie
      x-tags:
        - InitialActivation
        - Usage
        - Entitlement
        - DeliveryOrder
      description: |
        Retrieve all Usage information from a single Contract.
        Moreover, information from the DeliveryOrders and Entitlements is added to create a reporting overview of quantities entitled, licensed, and used.
        This endpoint is available for the `Bestelomgeving leermiddelen` and the `Aanspraakmanager`. No consent is required to receive the information.
        
        The `Licentieregistratie` is the provider of this endpoint.
        The `Aanspraakmanager` should give a 405 HTTP status as result when called.

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryOrderUsage'
        '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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method not allowed - Licentieregistratie is provider of this endpoint
      security:
        - OAuth2:
            - eduv.usage.seller
            - eduv.usage.entitlor
  
  # PUT endpoint for intitial activation messages send by `Licentieregistratie` to `Aanspraakmanager`

  /usage/activation:
    put:
      summary: Accept InitialActivation from Licentieregistratie
      operationId: accept-initial-activation
      tags:
        - Aanspraakmanager
      x-tags:
        - InitialActivation
      description: |
        Send an InitialActivation message to the `Aanspraakmanager` after a Student or Employee activated a Product.
        
        The `Aanspraakmanager` is the providers of this endpoint.
        The `Licentieregistratie` should give a 405 HTTP status as result when called.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitialActivation'
      responses:
        '202':
          description: Accepted
        '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'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method not allowed - Aanspraakmanager is provider of this endpoint
      security:
        - OAuth2:
            - eduv.usage.entitlor
  
x-tags:
  - name: InitialActivation
  - name: Usage
  - name: Entitlement
  - name: DeliveryOrder