...
Open api | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| openapi: 3.0.0
info:
title: Usage API
version: '0.9.1'
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 te 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: 0.9.1
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
| ||||||||||||
...
Release notes
0.0.1: Eerste draft van de API.
0.0.2: Objecten en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.
0.0.3: De technische specificatie is verder uitgewerkt. Ook is de feedback uit de werkgroepen verwerkt in een volgende versie:
Query parameter edu_org_id is toegevoegd aan alle endpoints als implementatie van Regie op gegevens en de M2M identificatie en authenticatie.
Het transactiepatroon melding bevestiging is toegepast voor het uitwisselen van de IntialActivation en Usage berichten. Dit heeft geresulteerd in PUT endpoints voor de meldingen voor de relevante referentiecomponenten.
BasispoortIDs zijn toegevoegd als opties voor Onderwijsdeelnemer, Onderwijsmedewerker en School.
In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.
0.0.4: De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.
0.0.5: Objecten geactualiseerd op basis van herziening rollen en referentiecomponenten in het architectuurkader.
0.0.6: De objecten en koppelvlakspecificatie inclusief de YAML zijn aangepast naar het nieuwe conceptueel model. Dit heeft geleid tot de volgende wijzigingen:
Aanspraken zijn van toepassing voor een enkele eindgebruiker. De voorheen open aanspraakvarianten zijn verplaatst naar de leveringsorders in de Delivery API
Aanspraken zijn er nog steeds in typen. De typen variëren vanuit de beoogde gebruiker: onderwijsdeelnemer, onderwijsmedewerker en een eindgebruiker met een activatiecode. Daarnaast zijn er aanspraken die toebehoren aan een onderwijsorganisatie.
De statusinformatie van aanspraken is gewijzigd en de statusinformatie van licenties is verwijderd. Een aanspraak is voor een enkele eindgebruiker en heeft nu een status van entitled, licensed en expired.
Het transactiepatroon voor het Leermiddelendashboard en de Bestelomgeving leermiddelen is gewijzigd naar een Bevraging. Het Leermiddelendashboard ontvang geen meldingen meer vanuit de Licentieregistratie.
Er zijn GET endpoints toegevoegd voor het Leermiddelendashboard
Er zijn GET endpoints toegevoegd voor de Bestelomgeving leermiddelen en de Aanspraakmanager om usage informatie op basis van een leveringsorderId en contractId op te vragen.
De scopes zijn aangepast met een specifieke scope voor de gegevensafnemende referentiecomponenten: Bestelomgeving leermiddelen, Aanspraakmanager en Leermiddelendashboard.
0.0.7: Er zijn wijzigingen verwerkt:
Wijzigen in de architectuur:
Attribuut schemaVersion is verwijderd uit de objecten.
Query parameter schemaVersion is verwijderd uit de koppelvlakken.
Query parameter edu_org_id is verwijderd uit de koppelvlakken waar consent voor nodig is.
Query parameters orgMasterId, orgId en orgIdType zijn toegevoegd om informatie over een onderwijsaanbieder op te vragen.
Primaire en secundaire identifiers voor onderwijsaanbieders en eindgebruikers bijgewerkt.
/ achter endpoints verwijderd.
0.9.0: Het Bestuurlijk Overleg heeft tijdens de bijeenkomst van 27 juni 2024 het Afsprakenstelsel Edu-V als versie 0.9.0 goedgekeurd voor implementatie.
0.9.1: Wijzigingen naar aanleiding van RFC’s:
Op basis van RFC002 is de scope aangepast met een prefix
eduv.
. Dit stelt leveranciers in staat om onderscheid te maken tussen gegevensuitwisselingen met leveranciers binnen en buiten het Edu-V afsprakenstelsel.De parameters voor paginering zijn uit de koppelvlakspecificatie verwijderd. Binnen het afsprakenstelsel zijn de afspraken hierover beschreven op de pagina paginering, sorteren en rate limiting.
De Vestigingserkenning is als secundaire identifier voor een onderwijsaanbieder verwijderd uit de koppelvlakspecificatie.