Edurep:Widget Endpoint: verschil tussen versies

Versie van 30 apr 2018 08:08

Voor de Widget wordt gebruik gemaakt van een JSON-endpoint die ook publiekelijk beschikbaar is. Deze pagina beschrijft de interfacing voor de JSON-endpoint. Het simpleJSON-endpoint wordt niet in detail uitgelegd.

Ook al staat de interface hier gespecificeerd, raden we aan om de gewenste zoekvraag via de Widget Wizard samen te stellen en aldaar te exporteren als JSON-query.

Het gebruik van deze endpoint valt niet onder de SLS van Edurep. We zijn wel van plan om deze dienstverlening definitief te maken.

Endpoint

https://proxy.edurep.nl/v3/search
https://proxy.edurep.nl/latest/search

Dit endpoint adres kan verouderen en worden vervangen door een nieuwere versie endpoint. Alleen de huidige en de vorige versie worden ondersteund (dus als versie 4 uitkomt wordt versie 2 niet meer ondersteund). Een alternatief is gebruik te maken van /latest/ ipv een versienummer.

Argumenten

Een overzicht van de ondersteunde argumenten:

naam	#	type	omschrijving
mode	1	string	Een der uitvoerformaten, json, simplejson, of rss.
query	1	cql query	Een zoekopdracht binnen LOM records.
startRecord	0-1	getal	De resultatenlijst wordt getoond vanaf dit record, standaard 1.
maximumRecords	0-1	getal	Het aantal records in de getoonde resultatenlijst, standaard 5, max 10.
x-term-drilldown	0-1	edurep zoekveld	Het veld waarop een term drilldown wordt gedaan voor de gevonden resultaten.
technicalFormats	0-1	een gemapt technisch formaat	Filtert de resultatenset op de gekozen formaten.
callback	0-1	een callback string	Wordt gebruikt voor JavaScript implementaties. Het meegeven resulteert in een JSONP respons.

Voorbeeld

JSON Respons v2 en v3

Aangezien het antwoord geen standaard NL LOM is, wat extra uitleg over het uitvoerformaat. Dit bestaat uit een aantal onderdelen:

config: De zoekopdracht zoals deze aan de endpoint werd meegegeven.
api-version: De versie van de JSON endpoint. De laatste versie is v3. Bij introductie van een nieuwe versie, bijv v4 dan zal v2 niet meer beschikbaar zijn. Nieuwe versies worden ruim van te voren aangekondigd zodat voldoende tijd is om te migreren.
status: Toont of er tijdens het zoeken en maken van het antwoord problemen waren.
caching: Toont caching informatie.
search: De gevonden individuele resultaten.
drilldowns: Drilldown informatie over de resultaatset.
navigation: Informatie voor het ophalen van de volgende "pagina" in de resultaatset.

Alleen de inhoud van search, drilldowns en navigation staat vast. Over de inhoud van de andere velden wordt geen garantie gegeven.

Search

Het "search" deel bevat algemene informatie over de zoekopdracht en een "records" deel waarin de metadata van elk record te vinden is. De velden van elk record zijn gebaseerd op een slimme combinatie van NL LOM, de collectielijst en eigen inzicht.

Zo is alle afbeeldingsinformatie (thumbnails, mimetype icon) gegroepeerd, net zoals informatie over collecties (identifier, naam, toegangsrechten). Vocabulairevelden bevatten een "value", een identifier waarde, maar ook een "human", die een waarde bevat voor menselijke interfaces.

schema

Er is een JSON Schema beschikbaar op GitHub. Dit schema geeft vooralsnog alleen een definitie van een record in een searchresult.

overzicht

In de volgende tabel staat een overzicht van de waarden in een record.

naam	cardinaliteit	type	omschrijving
title	1	string	titel
description	1	string	omschrijving
keyword	0-*	array	trefwoord(en), per entry één trefwoord.
language	1-*	string	de gebruikte talen in de bron, conform ISO 639-1 of "x-none"
aggregationlevel	1	string	het aggregatieniveau van de bron. Toegestane waarden "1", "2", "3" of "4".
publisher/name	0-*	string	de uitgever(s) van de bron
publisher/datetime	1	string	de laatste bekende publicatiedatum, conform ISO 8601 ("2009-10-22T05:23:12")
publisher/timestamp	1	integer	de laatste bekende publicatiedatum, conform Unix time (bijv. 1256181792)
author/name	0-*	string	de auteur(s) van de bron
author/datetime	1	string	de laatste bekende auteursdatum, conform ISO 8601 ("2009-10-22T05:23:12")
author/timestamp	1	integer	de laatste bekende auteursdatum, conform Unix time (bijv. 1256181792)
format/mimetype	1	string	bestandsformaat van bron, conform IANA mimetype of non-digital in geval van een fysiek product zoals een papieren boek.
format/mapped_format	1	string	identifier van het gemapte technische formaat
format/mapped_format_name	1	string	naam van het gemapte technische formaat
format/mapped_format_specific	1	string	naam van het specifieke gemapte technische formaat
learningresourcetype/human	1	string	Deze learningresourcetype is geen exacte vertaling van de waarde die in NL-LOM wordt aangeleverd. De waarde is daarin afhankelijk van het aggregationlevel veld. Indien deze waarde 1 of 2 is, dan wordt de bovenste waarde voor learningresourcetype in NL-LOM in dit veld overgenomen. Indien de waarde gelijk is aan 3, is deze waarde "Les", en indien de waarde gelijk is aan 4, is deze waarde "Serie lessen".
learningresourcetype/value	1	array	Een opsomming van de learningresourcetype waarden uit het oorspronkelijke record conform NL-LOM.
intendedenduserrole	0-*	array	mogelijke waarden voor intendedenduserrole
intendedenduserrole/human	1	string	presentatie waarde voor intendedenduserrole
intendedenduserrole/value	1	string	oorspronkelijke waarde voor intendedenduserrole uit het oorspronkelijke record conform NL-LOM.
context	0-*	string	educatieve sectoren waarin de bron toepasbaar is
typicalagerange	1	string	leeftijdsgroep waarvoor de bron toepasbaar is
cost/human	1	string	De presentatie waarde of de bron geld kost.
cost/value	1	string	De oorspronkelijke waarde uit NL-LOM.
copyright/human	1	string	De copyright vermelding zoals door de bron is aangeleverd.
copyright/value	1	string	De identifier van de copyright vermelding (of yes,no)
discipline/<uuid>	0-*	string	Een lijst van OBK inhouden (vakgebieden), zie ook het voorbeeld.
educationallevel/<uuid>	0-*	string	Een lijst van OBK leerniveaus, zie ook het voorbeeld.
educationalobjective/<uuid>	0-*	string	Een lijst van OBK leerdoelen, zie ook het voorbeeld.
time/seconds	1	integer	De aggregatie van het duration (afspeelduur) en het typicallearningtime (studielast) veld, waarbij typicallearningtime voorkeur geniet. De waarde is -1 als er geen waarde bekend is of niet van toepassing.
time/human	1	string	De time/seconds waarde uitgeschreven in menselijke presentabele tekst.
time/typicallearningtime	1	integer	studielast in seconden, -1 indien de waarde niet is opgegeven of niet van toepassing.
time/duration	1	integer	afspeelduur in seconden, indien -1 dan is er geen waarde opgegeven. Voorkeur is
repository/id	1	string	De Edurep identifier van de bron repository van het record.
repository/name	1	string	De naam van de bron repository van het record.
repository/accessrights/human	1	string	De menselijke tekst representatie voor de toegankelijkheid van de bron.
repository/accessrights/value	1	string	De identifier voor de toegankelijkheid van de bron. Deze informatie is afkomsting uit de collectielijst.
image/mimetype_icon	1	string	Een url naar een pictogram representatief voor het mimetype van de bron.
image/icon	0-1	string	Een url naar een door de record aanbieder bepaald pictogram voor de bron.
image/thumbnail	0-1	string	Een url naar een kleinere versie van de bron (afbeeldingsthumbnail of video still).
image/previewimage	0-1	string	Een aggregatie van thumbnail en icon. Als een van beide aanwezig is, staat deze ook in previewimage.
identifier/recordidentifier	1	string	De identifier van het metadatarecord in Edurep.
url/location	0-1	string	De url waar de bron te vinden is, indien de bron via het internet toegankelijk is.
url/embed	0-1	string	De embed-url van de bron waarmee de bron ge-embed kan worden in een andere pagina.
url/landingpage	0-1	string	Een landingpage link duidt op een pagina die niet de resource is, maar wel naar de resource linkt (de location link) wijst direct naar de resource.
social/nrofreviews	1	integer	Het aantal reviews bij deze bron.
social/nrofratings	1	integer	Het aantal ratings bij deze bron.
social/nroftags	1	integer	Het aantal tags bij deze bron.
social/rating	1	number	De genormaliseerde gemiddelde rating bij deze bron. Zie ook Edurep's geaggregeerde sociale metadata.

copyright

De value voor copyright kan een aantal waarden aannemen, yes, no, en een set Creative Commons identifiers. Er is altijd een corresponderende human waarde voor het aangegeven copyright type.

"copyright": {
    "value": "yes",
    "human": "For information on the use of archive material, please contact the Customer Service department of the Netherlands Institute for Sound and Vision: klantenservice@beeldengeluid.nl."
}

OBK

De secties discipline, educationallevel en educationalobjective bevatten informatie over vakgebied, leerniveau en leerdoel. De uuid identifiers zijn afkomsting uit het Onderwijs BegrippenKader.

"educationallevel": {
    "512e4729-03a4-43a2-95ba-758071d1b725": "Primair onderwijs",
    "2a1401e9-c223-493b-9b86-78f6993b1a8d": "Voortgezet onderwijs",
    "caa97efc-a713-41ea-a845-1534ca65eac9": "Beroepsonderwijs en Volwasseneneducatie"
}

time

De time sectie bevat de aggregatie van het duration (afspeelduur) en het typicallearningtime (studielast) veld, waarbij typicallearningtime voorkeur geniet. De waarde staat gerepresenteerd in seconden en in menselijke tekst,

"time": {
    "seconds": 951,
    "human": "16 minuten"
}

repository

De repostory sectie bevat informatie over de bron repository. De Edurep identifier staat aangegeven, alsmede de naam en de toegangsrechten. Deze informatie is afkomsting uit de collectielijst, daar staat ook de waardenset van de accessrights value.

"repository": {
    "id": "nationaalarchief",
    "name": "Nationaal Archief Beeldbank",
    "accessrights": {
        "human": "Openbaar",
        "value": "public"
    }
}

Drilldowns

De drilldowns worden per meegegeven veld teruggegeven net zoals in de reguliere respons. Alleen de vak en leerniveau drilldowns hebben een iets andere eigenschap, namelijk dat ze in boomvorm worden teruggegeven in plaats van als platte lijst. Het gaat daarmee specifiek over de volgende velden:

lom.classification.obk.discipline.id
lom.classification.obk.educationallevel.id

Bijvoorbeeld:

"lom.classification.obk.educationallevel.id": [
    {
        "identifier": "15d693b8-fbe1-4112-8135-4a20aba5101c",
        "caption": "Voor- en vroegschoolse educatie",
        "alternative": null,
        "records": 392,
        "purpose": "educationallevel",
        "parent": null,
        "children": [ ]
    },
    {
        "identifier": "512e4729-03a4-43a2-95ba-758071d1b725",
        "caption": "Primair onderwijs",
        "alternative": null,
        "records": 58730,
        "purpose": "educationallevel",
        "parent": null,
        "children": [
            {
                "identifier": "82ca4442-246c-44b3-a562-7b101793feb4",
                "caption": "PO groep 1",
                "alternative": null,
                "records": 6517,
                "purpose": "educationallevel",
                "parent": "512e4729-03a4-43a2-95ba-758071d1b725",
                "children": [ ]
            },
            {
                "identifier": "c007e4dd-a3d4-4f33-902d-778e3bbeeddb",
                "caption": "PO groep 2",
                "alternative": null,
                "records": 6713,
                "purpose": "educationallevel",
                "parent": "512e4729-03a4-43a2-95ba-758071d1b725",
                "children": [ ]
            }
        ]
    }
]

Technisch Formaat

De Widget proxy maakt een speciale mapping voor mimetypes zodat de veelheid aan mimetypes geaggregeerd worden naar een beperkte set logische technische formaten:

image: Afbeelding,
video: Video
audio: Audio
spreadsheet: Spreadsheet
presentation: Presentatie
text: Tekst
wikiwijsarrangement: Wikiwijs Arrangement
pdf: PDF
digiboard: Digiboard
app: App
archive: Archief
message: Bericht
ebook: eBook
googleearth: Google Earth

De losse mimetypes zijn als volgt gemapt naar de technische formaten.

mime type	technisch formaat	naam
application/x-yossymemo	digiboard	Hitachi StarBoard
application/x-ibooks+zip	ebook	iBook
image/bmp	image	Bitmap
application/vnd.openxmlformats-officedocument.presentationml.pre	presentation	Office Open Presentatie bestand
application/vnd.openxmlformats-officedocument.presentationml.sli	presentation	Office Open Diavoorstelling bestand
application/vnd.oasis.opendocument.spreadsheet	spreadsheet	OpenDocument Spreadsheet
application/postscript	text	PostScript
application/vnd.ms-word	text	Microsoft Word Document
application/x-tar	archive	TAR archief
application/vnd.ms-word.document.macroEnabled.12	text	Office Open XML
application/x-stuffit	archive	StuffIt Archief
application/x-koan	audio	Koan Audio
application/vnd.koan	audio	Koan Audio
audio/midi	audio	MIDI
application/vnd.openxmlformats-officedocument.wordprocessingml.template	text	Office Open XML
image/pjpeg	image	JPEG
text/rtf	text	Rich Text Format
application/Inspire	digiboard	Promethean ActivInspire bestand
message/rfc822	message	E-Mail
video/quicktime	video	Quicktime Video
application/x-AS3PE	digiboard	Promethean ActivStudio
application/vnd.ms-publisher	text	Office Publisher Document
application/vnd.google-earth.kmz	googleearth	Google Earth KMZ
image/png	image	PNG
video/x-msvideo	video	AVI
application/ppt	presentation	Office Powerpoint
application/x-rar-compressed	archive	RAR Archief
application/rtf	text	Rich Text Format
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	spreadsheet	Office Open Spreadsheet bestand
video/mpeg	video	MPEG
image/x-icon	image	Icoon
image/x-ms-bmp	image	Bitmap afbeelding
application/x-pdf	pdf	PDF
image/tiff	image	TIFF afbeelding
application/vnd.openxmlformats-officedocument.presentationml.slideshow	presentation	Office Open Diavoorstelling bestand
application/x-java	app	Java Applet
image/jpg	image	JPG
application/x-Inspire	digiboard	Promethean ActivInspire bestand
application/x-smarttech-notebook	digiboard	SMART Notebook
application/x-zip-compressed	digiboard	Heutink HD Board
application/x-ACTIVprimary3	digiboard	Promethean ActivPrimary
application/vnd.ms-excel	spreadsheet	Microsoft Excel bestand
text/plain	text	Tekst bestand
audio/x-wav	audio	WAV bestand
application/vnd.openxmlformats-officedocument.presentationml.presentation	presentation	Office Open Presentatie bestand
application/x-mplayer2	video	Web Video
image/gif	image	GIF afbeelding
audio/mpeg	audio	MP3 audio
application/vnd.openxmlformats-officedocument.wordprocessingml.document	text	Office Open Tekstverwerking bestand
video/mp4	video	MP4 video
application/vnd.ms-powerpoint	presentation	Microsoft Powerpoint bestand
video/x-ms-wmv	video	Windows Media Video
video/x-flv	video	Flash video
text/xml	text	XML bestand
application/msword	text	Microsoft Word Document
application/zip	archive	ZIP archief
video/x-ms-asf	video	ASF video
application/pdf	pdf	PDF
text/html	text	HTML pagina
image/jpeg	image	JPEG afbeelding
application/x-Wikiwijs-Arrangement	wikiwijsarrangement	Wikiwijs Arrangement

JSON Simple Respons

Dit is een versimpelde variant van de JSON respons en aan te roepen met mode "simplejson". Dit formaat bevat alleen title, description en url. Bijvoorbeeld:

{
    "title": "Frame (fiets)",
    "description": "Een frame is het dragende gedeelte (chassis) van een fiets, bromfiets of motorfiets. Het wordt ook wel rijwielgedeelte of kader genoemd.",
    "url": "http://nl.wikipedia.org/wiki/Frame_(fiets)"
}

RSS Respons

Een zoekopdracht is ook in het formaat RSS-feed op te vragen met mode=rss. Het formaat bevat alleen pubDate, title, link, description en guid. De RSS-feed wordt altijd op datum gesorteerd uitgeleverd met nieuwste leermiddel als eerste object. Daarnaast wordt altijd de laatste versie gebruikt, dus /v2/ of /v3/ redirect altijd /latest/. Het gebruikte content-type voor de RSS-feed is application/rss+xml; charset=utf-8.

Voorbeeld output van RSS-feed: https://proxy.edurep.nl/latest/search?mode=rss&query=edurep&maximumRecords=5

<?xml version="1.0" encoding="utf-8"?>
<rss xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
    <channel>
        <title>Kennisnet zoekopdracht</title>
        <link>https://proxy.edurep.nl/latest/search?mode=rss&amp;query=edurep&amp;maximumRecords=5</link>
        <atom:link href="https://proxy.edurep.nl/latest/search?mode=rss&amp;query=edurep&amp;maximumRecords=5" rel="self" type="application/rss+xml" />
        <description>Deze feed is afkomstig van Edurep, de zoekmachine voor lesmateriaal. Meer info is te vinden op: https://kn.nu/edurep-widget</description>
        <item>
            <pubDate>Fri, 08 Dec 2017 08:41:17 +0000</pubDate>
            <title><![CDATA[Git cheatsheet]]></title>
            <link><![CDATA[https://delen.edurep.nl/download/7fb81434-ef7e-4cf3-95de-e6dc5b1f4d75]]></link>
            <description><![CDATA[Een cheatsheet met de belangrijkste git-commando's op een rij voor bij je computer.]]></description>
            <guid><![CDATA[https://delen.edurep.nl/download/7fb81434-ef7e-4cf3-95de-e6dc5b1f4d75]]></guid>
        </item>
    </channel>
</rss>

@@ Regel 79: / Regel 79: @@
 ==== schema ====
-Er is een [http://json-schema.org JSON Schema] beschikbaar op [https://raw.githubusercontent.com/kennisnet/edurep-files/master/widget-jsonschema-04.json GitHub]. Dit schema geeft vooralsnog alleen een definitie van een record in een searchresult.
+Er is een [http://json-schema.org JSON Schema] beschikbaar op [https://raw.githubusercontent.com/kennisnet/edurep-files/master/schema/widget-jsonschema-04.json GitHub]. Dit schema geeft vooralsnog alleen een definitie van een record in een searchresult.
 ==== overzicht ====