Catalogue API

Titel	Catalogue API
Status	DRAFT WERKGROEP KLANKBORDgroep ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT
Stadium	POC PILOT BEHEER
Versie	0.0.3
Datum	11 Juli 2023
Auteur	Werkgroep Verwerven en in gebruik nemen
Acties	Geen openstaande acties

De Catalogue API wordt gebruikt om informatie over Leermiddelen uit te wisselen vanuit de Leermiddelenaanbieder naar de Leermiddelenshop, de Leerportaalaanbieder en de Dashboardaanbieder.

Het Product bevat alle informatie noodzakelijk voor het (laten) verwerven van leermiddelen. Ook bevat het Product de Toegangslink die geplaatst wordt in de Mijn Leermiddelen component. Deze Toegangslink wordt gebruikt voor het in gebruik nemen van een Leermiddel door een Onderwijsdeelnemer of -medewerker.

De technische specificatie bestaat uit:

1 Samenvatting
2 Berichtdefinitie: Product
- 2.1 Object courseReference
- 2.2 Object levelSubject
- 2.3 Object price
- 2.4 Object activationPeriod
- 2.5 Object mediaCollection
- 2.6 Object media
3 Status- en foutcodes
4 Technisch: API specificatie
5 Release notes

Samenvatting

Scopes	la.catalogue
Entiteiten	Product
Producer	Leermiddelenaanbieder – Leveranciersspecfieke leermiddelencatalogus
Consumer	Leermiddelenshop – Faciliteit voor leveren (of arrangeren) van digitale leermiddelen Leerportaalaanbieder – Mijn leermiddelen Leerportaalaanbieder – Learning Management System Dashboardaanbieder – Overkoepelend dashboard gebruik
Endpoints	Leverancierspecifieke leermiddelencatalogus GET Products GET Product by ID
Events API	De Events API kan gebruikt worden om als Consumer een notificatie te ontvangen bij een wijziging in de stand (nieuw/gewijzigd/verwijderd Product). Hiervoor dient zowel de Producer als de Consumer dan de Berichteninfrastructuur en de Events API te hebben geïmplementeerd. Buiten scope POC Berichteninfrastructuur voor het versturen en ontvangen van berichten Buiten scope POCEvents API

PoC Scope

Het notificeren bij wijzigingen in de Catalogue API is buiten de scope van de Proof of Concept.

Berichtdefinitie: Product

Het bericht Product beschrijft een LeermiddelBeschrijving of een SetBeschrijving. In de ProductBeschrijving is alle informatie opgenomen om het Product te kunnen tonen in een Leermiddelencatalogus een Leermiddelenshop voor oriënteren, selecteren en/of bestellen. Voor deze activiteiten kan een Leermiddelenaanbieder onder meer metadata over de toepassing in het onderwijs (levelSubjects), media (foto’s, video’s en documenten) en businessmodellen (models) toevoegen.

Via de velden status, forSale en de diverse datumvelden wordt de actuele status uit de levenscyclus van het Product gespecifieerd. Indien het Product een combiproduct betreft kan gebruik worden gemaakt van bundledProducts om de onderliggende Leermiddelen te specificeren. Tot slot is het mogelijk om voor ieder digitaal Leermiddel een referentie te maken naar een CursusBeschrijving uit de Course API.

PoC Scope

De link naar de Course API is buiten de scope van de POC.

Werkgroep combineren en arrangeren

De link naar de Course API is geplaatst om het combineren en arrangeren van leermaterialen mogelijk te maken. De detailuitwerking hiervan wordt gedaan binnen de werkgroep Combineren en arrangeren.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
productId	string	string	De unieke identifier voor het product.	871792713 0834	V	Voor producten die verkoopbaar zijn wordt er een ISBN of EAN gehanteerd. Voor overige producten genereert de Leermiddelenaanbieder een uuid. Waarde mag niet gewijzigd worden
schemaVersion	string	string	Het versienummer van de berichtdefinitie die wordt gehanteerd.	1.3.0	V	Conform Semantic Versioning 2.0.0
type	string	ENUM	Type-aanduiding voor het product.	physical digital combi	V	Waarde combi als het een combi-product betreft bestaande uit fysiek en digitale leermiddelen Waarde physical of digital als het product bestaat uit enkel fysieke of digitale leermiddelen Waarde mag niet gewijzigd worden
status	string	ENUM	Status uit de levenscyclus van een Leermiddel waar dit Product zich in bevindt.	not-yet-available limited-available available temporary-not-available no-longer-available will-never-be-available not-available-or-usable	V	Conform levenscyclus van Leermiddel, zie pagina Producten, Aanspraken en Licenties
forSale	boolean	boolean	Indicatie of het product verkoopbaar is.	True False	V	False, zodra het product niet te verkopen is. Bijvoorbeeld voor demo-producten Waarde mag niet gewijzigd worden
name	string	string	Benaming voor het product.	Getal & Ruimte 12^e ed havo/vwo bovenbouw online	V
product DescriptionIds	array	course Reference	Referentie naar de CursusBeschrijvingen die onderdeel zijn van dit Product	Zie object courseReference	O	Een Product kan verwijzen naar één of meerdere Courses. Een Course kan in één of meerdere Producten verkocht worden. De verwijzingen mogen niet wijzigen, foutcorrecties uitgezonderd. Dit veld blijft leeg voor een set van digitale leermiddelen.
levelSubjects	array	level Subject	Set van vakken, niveaus en leerjaren waar het product op is gericht.	Zie object levelSubject	O
price	array	price	De algemene verkoopprijs voor het product.	Zie object price	O	Het betreft de publieke prijsstelling voor het product Om prijswijzigingen (bijvoorbeeld indexatie) mogelijk te maken kunnen meerdere prijsstellingen gedeeld worden. Werkingsregel is om indien van toepassing de vorige prijs (t-1), de actuele prijs (t) en indien bekend de toekomstige prijs (t+1) te delen.
payment Models	array	payment Model (ENUM)	De betaalmodellen die ondersteund worden voor dit product.	pre-paid post-paid periodically-paid	O*	Verplicht als het product te verkopen is.
licensePeriod	string	ENUM	Duur van de licentieperiode op het product	month quarter year schoolyear	O*	Verplicht als het een digitaal product is.
activation Period	object	activation Period	Beschrijft de wijze waarop de Leermiddelenshop de activationUntilDate kan berekenen.	Zie object activationPeriod	O*	Verplicht als het product te verkopen is.
trial AccessUrl	string	url	Optionele URL naar een demo of trial omgeving	www.demo.nl	O
default AccessUrl	string	url	De Toegangslink naar het Leermiddel		O*	Verplicht om in te vullen als het type product digital of combi is. Voor combiproducten en sets van digitale leermiddelen wordt er een overkoepelende Toegangslink opgenomen van waaruit alle onderliggende digitale leermiddelen in gebruik zijn te nemen.
short Description	string	string	Korte omschrijving die getoond wordt in zoekpagina’s of product-beschrijvingen	-	V
long Description	string	string	Lange omschrijving die getoond wordt op productpagina	-	O
media	object	media Collection	Collectie van media objecten die getoond kunnen worden bij het Product	Zie object mediaCollection	O
related Products	array	productId	Array van producten die gerelateerd zijn aan dit Product en getoond kunnen worden bij dit Product.	Toetsproducten passend bij het Leermiddel Of andere Producten uit een reeks	O
bundled Products	array	productId	Array van Producten die onderdeel zijn van de Set of het Combiproduct	[8717927130834, 8717927130835, 8717927130836]	O*	Verplicht om in te vullen als het product een Setbeschrijving van digitale leermiddelen betreft. Advies is om voor combiproduct en ook de bundledProducts te vullen met onderliggende producten.
firstPublished Date	string	date	Datum dat product op de markt is verschenen of de verwachte verschijnings-datum	2022-08-01	V	Conform vullingsregels data passend bij status uit levenscyclus van Leermiddel, zie pagina Producten, Aanspraken en Licenties
depreciation Date	string	date	Vanaf deze datum is er een opvolger beschikbaar. Aangeraden wordt om deze te gebruiken.	2024-08-01	O*	Conform vullingsregels data passend bij status uit levenscyclus van Leermiddel, zie pagina Producten, Aanspraken en Licenties
supportedUntil Date	string	date	Vanaf deze datum is het product niet meer te bestellen.	2025-08-31	O*	Conform vullingsregels data passend bij status uit levenscyclus van Leermiddel, zie pagina Producten, Aanspraken en Licenties
endOfLifeDate	string	date	Na deze datum is het product niet meer beschikbaar.	2026-07-31	O*	Conform vullingsregels data passend bij status uit levenscyclus van Leermiddel, zie pagina Producten, Aanspraken en Licenties

Object courseReference

Een aantal van de attributen uit de Product berichtspecificatie zijn nader gespecificeerd. De productDescriptionIds verwijzen naar de CursusBeschrijvingen uit de Course API. Deze verwijzing is gespecificeerd in onderstaande tabel.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
courseId	string	string	Referentie naar courseId uit de Course API	-	V	Waarde mag niet gewijzigd worden
title	string	string	Naam van de CursusBeschrijving	-	O
description	string	string	Korte omschrijving van de CursusBeschrijving	-	O

Object levelSubject

Een Leermiddelenaanbieder kan optioneel specificeren voor welk vak en welke niveaus het Product ontwikkeld is. Hiervoor is het attribuut levelSubjects gespecificeerd in onderstaande tabel. Een Product kan van toepassing zijn op meerdere levelSubjects en/of meerdere levels binnen het subject.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
levels	array	levels	Een of meerdere niveaus en leerjaren waarop het Vak wordt gegeven.	Zie Tabel B-1	O	Dit kunnen er meerdere zijn in het geval van schoolLevel “Brugklas” of “Onderbouw”
subjectCode	string	ENUM	Officiële vakcode voor het vak	0131	O	Conform vakcodes uit de officiële vakcodetabel van Ministerie van OCW

Een SchoolVak bestaat uit de combinatie tussen Vak, Niveau en Leerjaar. Dit laatste niveau en leerjaar wordt gecombineerd in de array levels. De velden hierin zijn:

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
level	string	ENUM	Officieel niveau	VO-HAVO	V	Conform de officiële onderwijsniveaus.
levelYear	integer	integer	Het leerjaar dat gecombineerd wordt met het niveau.	1	V	Waarde 1-6

Tabel B-1. Specificatie velden van object levels

Voor level hanteren we een ENUM met de volgende officiële onderwijsniveaus (conform onderwijsniveaus van Dienst Uitvoering Onderwijs):

· BO: Basisonderwijs

· SO: Speciaal onderwijs

· SBO: Speciaal basisonderwijs

· VO-PRO: Praktijkonderwijs

· VO-VMBO-BB: Voorbereidend middelbaar beroepsonderwijs, basisberoepsgerichte leerweg

· VO-VMBO-KB: Voorbereidend middelbaar beroepsonderwijs, kaderberoepsgerichte leerweg

· VO-VMBO-GL: Voorbereidend middelbaar beroepsonderwijs, gemengde leerweg

· VO-VMBO-TL: Voorbereidend middelbaar beroepsonderwijs, theoretische leerweg

· VO-HAVO: Hoger algemeen voortgezet onderwijs

· VO-VWO: Voorbereidend wetenschappelijk onderwijs

· VSO: Voortgezet speciaal onderwijs

· MBO-Niveau-1: middelbaar beroepsonderwijs, niveau 1

· MBO-Niveau-2: middelbaar beroepsonderwijs, niveau 2

· MBO-Niveau-3: middelbaar beroepsonderwijs, niveau 3

· MBO-Niveau-4: middelbaar beroepsonderwijs, niveau 4

Object price

Een Leermiddelenaanbieder specificeert voor producten die verkocht kunnen worden de verkooprijzen in het object price. Een Leermiddelenshop kan deze informatie gebruiken om weer te geven op de productpagina van het product in een Leermiddelencatalogus. Een prijs wordt gespecificeerd conform onderstaande tabel.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
priceExcl	number	number	De prijs exclusief btw en afgerond op twee decimalen	18.34	V	Verplicht veld
priceIncl	number	number	De prijs inclusief btw en afgerond op twee decimalen	19.99	V	Verplicht veld
priceCurrency	string	currency	De munteenheid van de genoemde price	EUR DKK CHF	V	Conform ISO 4217 currency codes
validFrom	string	date	Ingangsdatum van de prijsstelling	2025-09-01	V	Verplicht veld

Object activationPeriod

De Leermiddelenshop specificeert in de aanspraak in welke periode een product in gebruik genomen kan worden: de activatieperiode. Dit betreft de met de Besteller overeengekomen startdatum en een volgens de Leermiddelenaanbieder voorgeschreven activationUntilDate. De Leermiddelenaanbieder neemt in de productBeschrijving op volgens welke regels de Leermiddelenshop deze activationUntilDate kan berekenen. Deze gegevens zijn beschreven in onderstaande tabel.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
activationVariant	string	ENUM	De variant die door de Leermiddelenshop gehanteerd wordt om de activiation UntilDate te berekenen.	days date schoolyear	V	Verplicht veld. Indien gekozen wordt voor schoolyear dan zet de Leermiddelenshop de activationUntilDate op 31 juli van het lopende schooljaar.
activiationDays	Integer	integer	Aantal dagen na de startDate van de activationPeriode	30	O*	Verplicht als activationVariant days is gekozen
activationUntilDate	string	date	Vaste activation UntilDate voor alle aanspraken op dit product.	2023-07-15	O*	Verplicht als activationVariant date is gekozen

Object mediaCollection

Een Leermiddelenaanbieder kan een Product voorzien van één of meerdere ondersteunende media zoals foto’s, video’s en documenten. Een van deze mediaobjecten betreft de basisminiatuur die ook gehanteerd wordt op zoekpagina’s van de Leermiddelencatalogus van een Leermiddelenshop. Alle media objecten behorende bij het Product worden gespecificeerd conform de specificatie van een mediaCollection in onderstaande tabel.

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
mainThumbnailUrl	object	media	Referentie naar een foto, video of document die getoond kan worden bij het product	Zie object media	O
productImageUrls	array	media	Een collectie van productfoto’s	Zie object media	O
productVideoUrls	array	media	Een collectie van productvideo’s	Zie object media	O
productPdfUrls	array	media	Een collectie van productdocumenten	Zie object media	O

Object media

Veld	Type	Format	Omschrijving	Voorbeeld	O/V	Vullingsregel
url	string	url	De url waar het mediaobject is opgeslagen		V
type	string	string	Het type van het mediaobject	image video pdf	O
description	string	string	Een korte omschrijving van het mediaobject, te gebruiken voor hover	Demovideo	O
width	integer	integer	De breedte van het mediaobject in pixels	500	V
height	integer	integer	De hoogte van het mediaobject in pixels	1000	V

Status- en foutcodes

Status code	Status	statusMessage	Toelichting
200	0	OK	Verzoek succesvol verwerkt
400	1	schema validation unsuccessful	Schemavalidatie niet succesvol
400	2	schemaVersion not supported	De ontvanger kan de gevraagde SchemaVersion niet aanbieden.
401	3	scope required	Client is niet geautoriseerd voor scope.
404	4	Product unknown	De identifier van het Product is 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. Ook is de feedback uit de werkgroepen verwerkt in een volgende versie:
- GET all endpoints zijn toegevoegd voor alle objecten.
- In de YAML is aangegeven welke referentiecomponent de endpoints aanbiedt als Producer.
- De YAML is geactualiseerd op basis van de bovenstaande wijzigingen.