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:

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.

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 12e 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.