Consent API

Titel	Consent API
Status	DRAFT ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT
Stadium	POC PILOT BEHEER
Versie	0.0.3
Datum	12 Juli 2023
Auteur	Architectenraad Edu-V
Acties	Geen acties

De Consent API is de technische implementatie van het proces van het (de)activeren van een gegevensuitwisseling voor een Onderwijsaanbieder (Consent).

De technische specificatie bestaat uit:

1 Samenvatting
2 Berichtdefinitie: Consent
3 Berichtdefinitie: Consentupdate
4 Status- en foutcodes
5 Technisch: API specificatie
6 Release notes

Samenvatting

Scopes	consent
Entiteiten	Consent ConsentUpdate
Producer	Registerhouder – Consentmanagement
Consumer	Registerhouder – Consentmanagement Dashboardaanbieder – Overkoepelend dashboard instemming
Endpoints	Consentmanagement POST Inform Consent Update GET Consents by School GET Consent by School and API

Zodra een Administrator van een Onderwijsaanbieder een gegevensuitwisseling heeft geactiveerd in een component Consentmanagement dan wordt de andere Leverancier op de hoogte gebracht van de activering. Hiervoor wordt gebruik gemaakt van het POST endpoint Inform Consent Update.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
producer ReferenceId	string	uuid	Unieke identifier gegenereerd door de Verzender (Producer) van de API met de gegevenssoort die is geactiveerd voor de Onderwijsaanbieder.	-	V	Let op! De Producer staat niet gelijk aan de leverancier die het POST endpoint inform consent aanbiedt. Het betreft de Verzender of bron van de API waarvoor een activering is gedaan. Voor de SIS API is dat bijvoorbeeld de Leverancier in de rol van Administratiesysteem-aanbieder.
consumer ReferenceId	string	uuid	Unieke identifier gegenereerd door de Ontvanger (Consumer) van de API met de gegevenssoort die is geactiveerd voor de Onderwijsaanbieder.	-	V	Let op! De Consumer staat niet gelijk aan de leverancier die het POST endpoint inform consent bevraagt. Het betreft de Ontvanger, of afnemer van de API waarvoor waarvoor een activering is gedaan. Voor de SIS API is dat bijvoorbeeld de Leverancier in de rol van Leermiddelenshop, Leermiddelenaanbieder, Leerportaalaanbieder of Dashboardaanbieder.
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
edu_org_id	string	string	Unieke identifier van de Onderwijsaanbieder waarvoor de gegevensuitwisseling is geactiveerd.	-	V
api	string	ENUM	De API met de gegevenssoort die is geactiveerd voor de Onderwijsaanbieder.	sis-api entitlement-api usage-api results-api	V	Betreft een API uit het Ecosysteem waarvoor activering een vereiste is voor uitwisseling.
scopes	array	ENUM	De scope van de gegevenssoort die is geactiveerd voor de Onderwijsaanbieder	sis.school sis.student-teacher-group sis.student-delivery ls.entitlement la.usage.activation la.usage.usage la.result	V	Betreft één of meerdere scopes van de geactiveerde api.
producer Status	string	ENUM	De (nieuwe) status van de activering	accepted declined revoked pending	V	In lijn met de beschrijving bij producer ReferenceId betreft het de status van de instemming bij de Verzender of bron (Producer) van de API waarvoor al dan niet instemming is verleend.
consumer Status	string	ENUM	De (nieuwe) status van de activering	accepted declined revoked pending	V	In lijn met de beschrijving bij consumer ReferenceId betreft het de status van de instemming bij de Ontvanger of afnemer (Consumer) van de API waarvoor al dan niet instemming is verleend.

Berichtdefinitie: Consentupdate

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
referenceId	string	uuid	Unieke identifier gegenereerd door de Leverancier bij wie de gegevensuitwisseling is geactiveerd.		V	In praktijk is dit altijd de Leverancier die het POST endpoint aanroept. Dit kan zowel de Verzender of bron (Producer) of de Ontvanger of afnemer (Consumer) van de gegevens zijn.
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
edu_org_id	string	string	Unieke identifier van de Onderwijsaanbieder waarvoor de gegevensuitwisseling is geactiveerd.	-	V	Een Consent wordt geregistreerd op het niveau van een Onderwijsaanbieder. Indien er in de component Consentmanagement een instemming is verleend op een hoger niveau in de organisatie van de school (bijvoorbeeld op Onderwijsbestuur) dan wordt er voor alle onderliggende Onderwijsaanbieders een Inform Consent Update verstuurd.
api	string	ENUM	De API met de gegevenssoort die is geactiveerd voor de Onderwijsaanbieder.	sis-api entitlement-api usage-api results-api	V	Betreft een API uit het Ecosysteem waarvoor activering een vereiste is voor uitwisseling.
scopes	array	ENUM	De scope van de gegevenssoort die is geactiveerd voor de Onderwijsaanbieder	sis.school sis.student-teacher-group sis.student-delivery ls.entitlement la.usage.activation la.usage.usage la.result	V	Betreft één of meerdere scopes van de geactiveerde api.
newStatus	string	ENUM	De (nieuwe) status van de activering	accepted declined revoked	V	De status kan bijvoorbeeld wijzigen zodra een Applicatiebeheerder een gegevensuitwisseling deactiveerd.

Status- en foutcodes

Status code	Status	statusMessage	Omschrijving
200	0	OK	Consent geregistreerd
400	1	Schema incorrect	Schemavalidatie niet succesvol
400	2	schemaVersion not supported	De ontvanger kan de gehanteerde schemaVersion niet verwerken
400	3	referenceId already used for different API/School combination	referenceId al een keer gebruikt
401	4	scope required	Leverancier is niet geautoriseerd voor scope consent
404	5	School unknown	Onderwijsaanbieder onbekend
404	6	referenceId unknown	Referentie naar consent onbekend
400	99	Vullingsregel: in statusMessage een beschrijving van de reden opnemen	Overige reden

Technisch: API specificatie

Release notes

0.0.1: Eerste draft van de API.
0.0.2: Berichtdefinities en YAML files zijn toegevoegd t.b.v. de 80 procent specificatie.
0.0.3: De technische specificatie is verder uitgewerkt.
- edu_org_id is toegevoegd aan alle endpoints als implementatie van het activeren en deactiveren van gegevensuitwisselingen en de M2M identificatie en authenticatie.
- scopes zijn toegevoegd aan het object consent. Het is daarmee mogelijk om een consent te registreren voor een specifieke gegevenssoort uit een API.
- De status- en foutcodes zijn toegevoegd aan de documentatie en aan de YAML.
- In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
- De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.