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 |
|
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:
Samenvatting
Scopes |
|
Entiteiten |
|
Producer |
|
Consumer |
|
Endpoints | Leverancierspecifieke leermiddelencatalogus
|
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.
|
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 | 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 12e ed havo/vwo bovenbouw online | V |
|
product | array | course | 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 | 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 | array | payment | 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 | object | activation | Beschrijft de wijze waarop de Leermiddelenshop de activationUntilDate kan berekenen. | Zie object activationPeriod | O* | Verplicht als het product te verkopen is. |
trial | string | url | Optionele URL naar een demo of trial omgeving | O |
| |
default | 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 | string | string | Korte omschrijving die getoond wordt in zoekpagina’s of product-beschrijvingen | - | V |
|
long | string | string | Lange omschrijving die getoond wordt op productpagina | - | O |
|
media | object | media | Collectie van media objecten die getoond kunnen worden bij het Product | Zie object mediaCollection | O |
|
related | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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.