Edurep:Widget Endpoint: verschil tussen versies

Uit Kennisnet Developers Documentatie
Naar navigatie springen Naar zoeken springen
(→‎image: uitleg)
(→‎Argumenten: update query link)
 
(35 tussenliggende versies door 2 gebruikers niet weergegeven)
Regel 1: Regel 1:
−
Voor de [[Edurep:Widget|Widget]] wordt gebruik gemaakt van een JSON endpoint die ook voor het grotere publiek beschikbaar is. Deze pagina beschrijft de interfacing voor de JSON endpoint. De simple JSON endpoint wordt niet in detail uitgelegd.
+
Voor de [[Edurep:Widget|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 [https://www.kennisnet.nl/edurep/edurep-widgets/ Widget Wizard] samen te stellen en aldaar te exporteren als JSON-query.
  +
{{Info|Het gebruik van deze endpoint valt niet onder de [https://www.kennisnet.nl/edurep/aanmelden/ SLS] van Edurep. We zijn wel van plan om deze dienstverlening definitief te maken.}}
  +
{{Warn|Dit endpoint heeft End of Life status bereikt. De [[Edurep:Jsonsearch|Jsonsearch]] kan gebruikt worden als vervangende interface.}}
   
−
Ook al staat de interface hier gespecificeerd, raden we aan om de gewenste zoekvraag via de [http://www.kennisnet.nl/diensten/edurep/zoeken-naar-leermateriaal/edurep-widget/ Widget Wizard] samen te stellen en aldaar te exporteren als JSON query.
  
   
 
== Endpoint ==
  
== Endpoint ==
−
* <nowiki>https://proxy.edurep.nl/v2/search?mode=json</nowiki>
 +
* <nowiki>https://proxy.edurep.nl/v3/search</nowiki>
  +
* <nowiki>https://proxy.edurep.nl/latest/search</nowiki>
   
−
{{Info|Dit endpoint adres kan verouderen en vervangen worden door een nieuwere versie endpoint.}}
 +
{{Info|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 ==
  
== Argumenten ==
Regel 15: Regel 19:
 
! type
  
! type
 
! omschrijving
  
! omschrijving
  +
|-
  +
|mode
  +
|1
  +
|string
  +
|Een der uitvoerformaten, json, simplejson, of rss.
 
|-
  
|-
 
|query
  
|query
 
|1
  
|1
−
|[[Edurep:CQL|cql query]]
 +
|[[Edurep:Zoekopdracht/Query|cql query]]
 
|Een zoekopdracht binnen LOM records.
  
|Een zoekopdracht binnen LOM records.
 
|-
  
|-
Regel 29: Regel 38:
 
|0-1
  
|0-1
 
|getal
  
|getal
−
|Het aantal records in de getoonde resultatenlijst, standaard 10, max 100.
 +
|Het aantal records in de getoonde resultatenlijst, standaard 5, max 10.
 
|-
  
|-
 
|x-term-drilldown
  
|x-term-drilldown
Regel 38: Regel 47:
 
|technicalFormats
  
|technicalFormats
 
|0-1
  
|0-1
−
|een [[Edurep:JSON_Endpoint#Technisch Formaat|gemapt technisch formaat]]
 +
|een [[Edurep:Widget_Endpoint#Technisch Formaat|gemapt technisch formaat]]
 
|Filtert de resultatenset op de gekozen formaten.
  
|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.
 
|-
  
|-
 
|}
  
|}
   
−
== Respons ==
 +
=== Voorbeeld ===
  +
* https://proxy.edurep.nl/v3/search?mode=json&query=fiets
  +
* https://proxy.edurep.nl/v3/search?mode=json&query=fiets&x-term-drilldown=lom.classification.obk.educationallevel.id
  +
* https://proxy.edurep.nl/v3/search?mode=json&query=fiets&technicalFormats=video&x-term-drilldown=lom.classification.obk.educationallevel.id
  +
  +
== JSON Respons v2 en v3 ==
 
Aangezien het antwoord geen standaard {{Standaard|NL LOM}} is, wat extra uitleg over het uitvoerformaat. Dit bestaat uit een aantal onderdelen:
  
Aangezien het antwoord geen standaard {{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.
  
* 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.
−
* api-version: De versie van de JSON endpoint.
  
 
* status: Toont of er tijdens het zoeken en maken van het antwoord problemen waren.
  
* status: Toont of er tijdens het zoeken en maken van het antwoord problemen waren.
 
* caching: Toont caching informatie.
  
* caching: Toont caching informatie.
Regel 52: Regel 71:
 
* drilldowns: Drilldown informatie over de resultaatset.
  
* drilldowns: Drilldown informatie over de resultaatset.
 
* navigation: Informatie voor het ophalen van de volgende "pagina" in de resultaatset.
  
* navigation: Informatie voor het ophalen van de volgende "pagina" in de resultaatset.
  +
  +
{{Info|Alleen de inhoud van search, drilldowns en navigation staat vast. Over de inhoud van de andere velden wordt geen garantie gegeven.}}
   
 
=== Search ===
  
=== Search ===
Regel 58: Regel 79:
 
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.
  
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.
   
−
==== author, publisher ====
 +
==== schema ====
  +
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.
−
Een author of een publisher veld bevat 0 of meerdere namen, en een datum die duidt op de laatste bekende publicatie- of auteursdatum. De datum staat eveneens vermeld als [http://en.wikipedia.org/wiki/Unix_time Unix time].
  
−
<syntaxhighlight lang="javascript">
  
−
"publisher": {
  
−
"name": [
  
−
"YouTube"
  
−
],
  
−
"datetime": "2014-03-04T19:30:02",
  
−
"timestamp": 1393957802
  
−
}
  
−
</syntaxhighlight>
  
   
−
==== format ====
 +
==== overzicht ====
  +
In de volgende tabel staat een overzicht van de waarden in een record.
−
Het format veld bevat alle informatie over het technische format, waaronder het mimetype, maar ook informatie over het [[Edurep:JSON_Endpoint#Technisch Formaat|gemapte technische formaat]].
  
  +
{| class="wikitable"
−
<syntaxhighlight lang="javascript">
  
  +
! naam
−
"format": {
  
  +
! cardinaliteit
−
"mimetype": "video/x-flv",
  
  +
! type
−
"mapped_format": "video",
  
  +
! omschrijving
−
"mapped_format_name": "Video",
  
  +
|-
−
"mapped_format_specific": "Flash video"
  
  +
| title
−
}
  
  +
| 1
−
</syntaxhighlight>
  
  +
| string
−  
  +
| titel
−
==== learningresourcetype ====
  
  +
|-
−
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".
  
  +
| description
−
<syntaxhighlight lang="javascript">
  
  +
| 1
−
learningresourcetype": [
  
  +
| string
−
"informatiebron"
  
  +
| omschrijving
−
]
  
  +
|-
−
</syntaxhighlight>
  
  +
| keyword
−
{{Info|De structuur van dit veld gaat binnenkort wijzigen.}}
  
  +
| 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 [[Standaarden:NL_LOM/lom.general.aggregationlevel|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 [http://en.wikipedia.org/wiki/Unix_time 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 [http://en.wikipedia.org/wiki/Unix_time 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 [[Edurep:Widget_Endpoint#Technisch Formaat|gemapte technische formaat]]
  +
|-
  +
| format/mapped_format_name
  +
| 1
  +
| string
  +
| naam van het [[Edurep:Widget_Endpoint#Technisch Formaat|gemapte technische formaat]]
  +
|-
  +
| format/mapped_format_specific
  +
| 1
  +
| string
  +
| naam van het specifieke [[Edurep:Widget_Endpoint#Technisch Formaat|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 [[#OBK|voorbeeld]].
  +
|-
  +
| educationallevel/<uuid>
  +
| 0-*
  +
| string
  +
| Een lijst van OBK leerniveaus, zie ook het [[#OBK|voorbeeld]].
  +
|-
  +
| educationalobjective/<uuid>
  +
| 0-*
  +
| string
  +
| Een lijst van OBK leerdoelen, zie ook het [[#OBK|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 [[Edurep:Collecties|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:SAD|Edurep's geaggregeerde sociale metadata]].
  +
|}
   
 
==== copyright ====
  
==== copyright ====
Regel 102: Regel 348:
 
De secties discipline, educationallevel en educationalobjective bevatten informatie over vakgebied, leerniveau en leerdoel. De uuid identifiers zijn afkomsting uit het [[OBK:Hoofdpagina|Onderwijs BegrippenKader]].
  
De secties discipline, educationallevel en educationalobjective bevatten informatie over vakgebied, leerniveau en leerdoel. De uuid identifiers zijn afkomsting uit het [[OBK:Hoofdpagina|Onderwijs BegrippenKader]].
 
<syntaxhighlight lang="javascript">
  
<syntaxhighlight lang="javascript">
−
educationallevel": {
 +
"educationallevel": {
 
"512e4729-03a4-43a2-95ba-758071d1b725": "Primair onderwijs",
  
"512e4729-03a4-43a2-95ba-758071d1b725": "Primair onderwijs",
 
"2a1401e9-c223-493b-9b86-78f6993b1a8d": "Voortgezet onderwijs",
  
"2a1401e9-c223-493b-9b86-78f6993b1a8d": "Voortgezet onderwijs",
Regel 110: Regel 356:
   
 
==== time ====
  
==== 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,
 +
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,
 
<syntaxhighlight lang="javascript">
  
<syntaxhighlight lang="javascript">
 
"time": {
  
"time": {
Regel 128: Regel 374:
 
"value": "public"
  
"value": "public"
 
}
  
}
−
}
  
−
</syntaxhighlight>
  
−  
−
==== image ====
  
−
De image sectie bevat eventuele links naar bepaalde afbeeldingstypen. Een thumbnail is een kleinere variant van de bron (afbeeldingen en video's), terwijl een icon vaak illustratief is. Indien 1 van beide aanwezig is, staat deze altijd ook in previewimage.
  
−
<syntaxhighlight lang="javascript">
  
−
image": {
  
−
"mimetype_icon": "http://widget.edurep.nl/icon/mimetypes/openworld/48/video/x-flv.png",
  
−
"icon": "",
  
−
"thumbnail": "https://i.ytimg.com/vi/qFDjVfXN16U/default.jpg",
  
−
"previewimage": "https://i.ytimg.com/vi/qFDjVfXN16U/default.jpg"
  
−
}
  
−
</syntaxhighlight>
  
−  
−
==== url ====
  
−
De url sectie bevat alle links naar de daadwerkelijke resource. Een embed link wordt typisch gebruikt bij videomateriaal. 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.
  
−
<syntaxhighlight lang="javascript">
  
−
url": {
  
−
"location": "http://www.youtube.com/watch?v=qFDjVfXN16U",
  
−
"embed": "http://www.youtube.com/embed/qFDjVfXN16U",
  
−
"landingpage": ""
  
−
}
  
−
</syntaxhighlight>
  
−  
−
==== social ====
  
−
De social sectie is een directe vertaling van Edurep's [[Edurep:SAD|geaggregeerde sociale metadata]], waarbij rating the average normalized rating is.
  
−
<syntaxhighlight lang="javascript">
  
−
"social": {
  
−
"nrofreviews": 0,
  
−
"nrofratings": 0,
  
−
"nroftags": 0,
  
−
"rating": 0
  
 
}
  
}
 
</syntaxhighlight>
  
</syntaxhighlight>
Regel 230: Regel 444:
   
 
De losse mimetypes zijn als volgt gemapt naar de technische formaten.
  
De losse mimetypes zijn als volgt gemapt naar de technische formaten.
−
{| class="wikitable"
 +
{| class="wikitable sortable"
 
! mime type
  
! mime type
 
! technisch formaat
  
! technisch formaat
Regel 480: Regel 694:
 
|-
  
|-
 
|}
  
|}
  +
  +
== 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:
  +
<syntaxhighlight lang="javascript">
  +
{
  +
"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)"
  +
}
  +
</syntaxhighlight>
  +
  +
== 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&amp;query=edurep&amp;maximumRecords=5
  +
<syntaxhighlight lang="xml">
  +
<?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>
  +
</syntaxhighlight>
  +
   
 
[[Categorie:Edurep]]
  
[[Categorie:Edurep]]

Huidige versie van 21 okt 2021 om 04:02

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.

Info.gif Het gebruik van deze endpoint valt niet onder de SLS van Edurep. We zijn wel van plan om deze dienstverlening definitief te maken.
Warn.gif Dit endpoint heeft End of Life status bereikt. De Jsonsearch kan gebruikt worden als vervangende interface.


Endpoint

  • https://proxy.edurep.nl/v3/search
  • https://proxy.edurep.nl/latest/search
Info.gif 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.
Info.gif 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>
Overgenomen van "https://developers.wiki.kennisnet.nl/index.php?title=Edurep:Widget_Endpoint&oldid=11631"