Documentatie Content API

Opvoedinformatie Nederland Content API

Laatst gewijzigd op: 10 februari 2020

Algemeen

Opvoedinformatie Nederland biedt landelijk gevalideerde content aan op het gebied van opgroeien, opvoeden en gezondheid. Door de combinatie van deze content wordt de betrouwbare informatie op een prettige en effectieve manier toegankelijk voor ouders en opvoeders. Opvoedinformatie Nederland heeft de publieke verantwoordelijkheid voor het onderdeel ‘content’. Dit document geeft een toelichting op het gebruik en de mogelijkheden van de API dat wordt aangeboden om deze content te ontsluiten.

Content

De landelijke database wordt via Opvoedinformatie Nederland gehost en kan door een derde partij worden opgehaald via onze API.

Gebruikersvoorwaarden

Aan het gebruik van de API stelt Opvoedinformatie Nederland voorwaarden die je accepteert bij het gebruik van de API. De voorwaarden zijn na te lezen op Opvoedinformatie.nl.

Toegang en beveiliging

De content is alleen toegankelijk met een API-Token. Heb je nog geen token? Vraag deze dan bij ons aan.

Vragen?

Alle informatie over de technische ontwikkelingen vind je op deze informatiepagina. Neem bij vragen contact op via contact@opvoedinformatie.nl of 088-11 80 200. Vermeld hierbij het IP-adres waarvandaan je de API benaderd.

Responsetijden

Wij streven er naar om je vraag binnen 8 (kantoor)uren te beantwoorden.

Inhoud

Requests

De basis URL van de REST API van Opvoedinformatie Nederland is als volgt:

https://api.opvoedinformatie.nl/v1/

Bij elk request dienen er twee HTTP-requestheaders meegestuurd te worden, genaamd ‘Authorization’ en ‘ConsumerReference’.

De Authorization-header moet de API-token bevatten met een Bearer-prefix. De ConsumerReference-header moet een unieke referentie bevatten voor welke klant de API op dat moment benaderd wordt. De waarde van deze header mag zelf bepaald worden, maar moet uniek per klant zijn.

GET /v1/{endpoint} HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam

Terug naar boven

Endpoints

De API biedt verschillende endpoints om informatie op te halen welke hierna beschreven worden. Alle API-responses zijn in JSON-formaat.

Terug naar boven

/collections

De content is onderverdeeld in collecties en elke collectie is voorzien van een keurmerk dat onder de content getoond dient te worden. Zie hiervoor de gebruiksvoorwaarden.

De collections-endpoint geeft een array van contentcollecties terug die beschikbaar zijn.

GET /v1/collections HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam

De response heeft het volgende formaat:

[
  {
      "id": 1,
      "collection": "Opvoedencontent",
      "qualityMark: {
          "url": "https://www.opvoeden.nl/keurmerk/",
          "text": "Opvoedinformatie Nederland zorgt er met ouders en deskundigen uit de wetenschap en praktijk voor dat deze informatie betrouwbaar en actueel blijft."
          "imageAlt": "Het keurkmerk van de betrouwbare opvoedinformatie van Opvoedinformatie Nederland"
          "imageUrl": "https://content.opvoedinformatie.nl/images/keurmerk-opvoedencontent",
      }
  },
  {
     "id": 2,
     "collection": "Jongerencontent",
     "qualityMark: {
         "url": "https://www.infovoorjou.nl/keurmerk/",
         "text": "Opvoedinformatie Nederland zorgt er met jongeren en deskundigen uit de wetenschap en praktijk voor dat deze informatie betrouwbaar en actueel blijft."
         "imageUrl": "https://content.opvoedinformatie.nl/images/keurmerk-jongerencontent",
         "imageAlt": "Het keurkmerk van de betrouwbare opvoedinformatie van Opvoedinformatie Nederland"
     }
 },
 {
     "id": 3,
     "collection": "Kindercontent",
     "qualityMark: {
         "url": "https://www.infovoorkinderen.nl/keurmerk/",
         "text": "Opvoedinformatie Nederland zorgt er met kinderen en deskundigen voor dat deze informatie betrouwbaar en actueel blijft."
         "imageUrl": "https://content.opvoedinformatie.nl/images/keurmerk-kindercontent",
         "imageAlt": "Het keurkmerk van de betrouwbare opvoedinformatie van Opvoedinformatie Nederland"
     }
 }
]

Terug naar boven

/content-types

In de content zijn verschillende typen content aanwezig zoals artikelen en beeldverhalen. Je kunt de content per type ophalen. Het type artikel spreekt voor zich. Klik hier voor meer informatie over beeldverhalen.

De content-types-endpoint geeft een array van contenttypes terug.

GET /v1/content-types HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam

De response heeft het volgende formaat:

[
 {
  "id": 1,
  "type": "Artikel"
 },
 {
  "id": 2,
  "type": "Beeldverhaal"
 }
]

Terug naar boven

/language-levels

Taalniveaus zeggen iets over het leesniveau dat nodig is om de content te kunnen begrijpen. Beeldverhalen zijn voor laaggeletterden en is daarom op taalniveau A1 geschreven. De kindercontent is van een iets hoger niveau: A2. De jongeren- en de opvoedencontent is geschreven op B1 niveau.

De language-levels-endpoint geeft een array van taalniveaus terug.

GET /v1/language-levels HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam

De response heeft het volgende formaat:

[
 {
  "id": 1,
  "languageLevel": "A1"
 },
 {
  "id": 2,
  "languageLevel": "A2"
 },
 {
  "id": 3,
  "languageLevel": "B1"
 }
]

Terug naar boven

/audiences

Content kan voor verschillende doelgroepen geschreven zijn. Daarom kun je de content ophalen op basis van doelgroep.

De audiences-endpoint geeft een array van doelgroepen terug. Content kan meerdere doelgroepen hebben.

GET /v1/audiences HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam

De response heeft het volgende formaat:

[
 {
  "id": 1,
  "audience": "Aanstaande ouders"
 },
 {
  "id": 2,
  "audience": "Jongeren (12-18)"
 },
 {
  "id": 3,
  "audience": "Kinderen (8-12)"
 },
 {
  "id": 4,
  "audience": "Mensen met kinderwens"
 },
 {
  "id": 5,
  "audience": "Ouders"
 }
]

Terug naar boven

/subjects

De content is getagd met meerdere taxonomietermen (onderwerpen) en kan opgehaald worden op basis van deze termen. De termen zeggen iets over de inhoud van de content.

De subjects-endpoint geeft een array van onderwerpen terug. Content kan meerdere subjects hebben.

GET /v1/subjects HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam

De response heeft het volgende formaat:

[
  {
          "id": 1,
          "subject": "Levensfase",
          "parentId": null,
          "synonyms": []
      },
      {
          "id": 2,
          "subject": "Baby",
          "parentId": 1,
          "synonyms": []
      },
      {
          "id": 3,
          "subject": "Baby 0",
          "parentId": 2,
          "synonyms": []
      },
      {
          "id": 4,
          "subject": "Baby 1",
          "parentId": 2,
          "synonyms": []
      },
      {
          "id": 5,
          "subject": "Peuter",
          "parentId": 1,
          "synonyms": []
      },
      ... etc
]

De onderwerpen waarmee content getagged kan zijn, staan in een hiërarchische structuur van maximaal 3 lagen diep. De parentId property geeft aan welk ander subject object de “parent” is. Als in een contentquery een onderwerp gebruikt wordt van een hoger niveau dan wordt ook content gematched die getagged zijn met onderwerpen op een lager gelegen niveau. Bijvoorbeeld onder het onderwerp “Baby” zijn twee dieper gelegen onderwerpen aanwezig genaamd “Baby 0” en “Baby 1”. Indien er in de contentquery gebruik wordt gemaakt van het onderwerp “Baby” dan zal ook content gematched worden die getagged is met “Baby 0” of “Baby 1”.

De synonyms property is een array van strings van synoniemen voor het onderwerp.

Terug naar boven

/content/{id}

De content/{id}-endpoint wordt gebruikt om content op te halen aan de hand van een specifiek identificatienummer.

GET /v1/content/{id} HTTP/1.1
Host: https://api.opvoedinformatie.nl
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam

De response heeft het volgende formaat:

  {
      "identifier": 123,
      "title": "Titel van de content",
      "abbreviation": "De verkorte titel van de content",
      "type": "Artikel",
      "authority": "Opvoedinformatie Nederland",
      "publisher": "Opvoedinformatie Nederland",
      "issued": "2018-10-25T15:04:25.81071",
      "modified": "2018-10-25T15:04:25.81071",
      "dateAccepted": "2018-10-25T15:04:25.81071",
      "available": {
          "start": "2018-10-25T15:04:25.81071",
          "end": null
      },
      "sources": null,
      "abstract": "De samenvatting van de content",
      "extent": "Aantal woorden in de content",
      "format": "text/html",
      "subject": [
          {
              "id": 1,
              "subject": "Onderwerp 1",
              "parentId": null,
              "synonyms": []
          },
          {
              "id": 2,
              "subject": "Onderwerp 2",
              "parentId": null,
              "synonyms": []
          }
      ],
      "audience": [
          "Doelgroep 1",
          "Doelgroep 2"
      ],
      "language": "nl_NL",
      "languageLevel": "B1",
      "collection": "Opvoedencontent",
      "parentIdentifier": 1,
      "hierarchicalOrder": 3,
      "structuralContent": false,
      "canonicalUrl": "https://www.opvoeden.nl/url-van-content",
      "content": {
          "body": "lorem ipsum"
      }
  }

De properties in de response worden verderop beschreven.

Terug naar boven

/content

De content-endpoint wordt gebruikt om content op te halen aan de hand van een contentquery. Een contentquery is een zoekopdracht in JSON-formaat en wordt als Request Body in een POST-request naar de content-endpoint gestuurd. Voor dit request dient ook de “Content-Type” HTTP-header aanwezig te zijn met als waarde “application/json”.

POST /v1/content HTTP/1.1
Host: https://api.opvoedinformatie.nl
Content-Type: application/json
Authorization: Bearer {API-Token}
ConsumerReference: Klantnaam
{
 "collections": ["Opvoedencontent"],
 "audiences": ["Ouders"],
 "languageLevels": ["B1"],
 "types": ["Artikel"],
 "subjects":
 [
  ["Baby 0", "Veiligheid"],
  ["Ouderschap", "Veiligheid"]
 ]
}

In een contentquery kunnen de volgende filters gedefinieerd worden:

collections (verplicht) Een array van de collecties waarvan de content opgehaald moet worden. Deze property is verplicht.
audiences Een array van doelgroep(en) waarvoor de content bestemd moet zijn.
languageLevels Een array van taalniveaus waarin de content geschreven moet zijn.
types Een array van contenttypes van de content die opgehaald moet worden.
subjects Een tweedimensionale array van onderwerpen waarmee de content getagged moet zijn. Op onderwerpen in de binnenste arrays wordt een “AND” operator toegepast. Op de buitenste array wordt een “OR” operator toegepast. In bovenstaand voorbeeld wordt content opgehaald die getagged zijn met (“Baby 0” AND “Veiligheid”) OR (“Ouderschap” AND “Veiligheid”).
modifiedSince De datum wanneer het object voor het laatst gewijzigd is. Wijzigingen betreffen niet alleen inhoudelijke wijzigingen in de content maar ook wijzigingen aan bijvoorbeeld de metadata of hiërarchische positie van het object zelf of één van de bovenliggende objecten.
includeAvailable Een boolean die aangeeft of gepubliceerde content in het antwoord aanwezig moet zijn. Deze eigenschap staat standaard op true.
includeRemoved Een boolean die aangeeft of gedepubliceerde content in het antwoord aanwezig moet zijn. Deze eigenschap staat standaard op false. Gedepubliceerde content is te herkennen aan de eigenschap “available.end”. Deze eigenschap heeft dan de datum van vandaag of een datum in het verleden.

Op de collectionsfilter na zijn alle overige filters optioneel.

De response van de “content” endpoint is een array van objecten, waarvan het formaat gelijk is aan de endpoint “content/{id}”.

Terug naar boven

Navigatiestructuur

Wanneer je de content wilt gebruiken met een voorgedefinieerde navigatiestructuur dan maak je deze structuur met de proporties parentIdentifier en hierarchicalOrder. Zie Properties van een content object.

De structuur die je met deze properties opbouwt, is anders dan de structuur die je op Opvoeden.nl ziet. De structuur van Opvoeden.nl is samengesteld op basis van taxonomie.

Terug naar boven

Koppelteksten

De navigatiestructuur wordt opgebouwd met teksten die specifiek voor deze structuur zijn gemaakt. Je herkent deze teksten aan de propertie structuralContent die als waarde ’true’ heeft. Zie Properties van een content object.

De teksten waarmee deze structuur is opgebouwd hebben een andere status dan de rest van de content. Alle teksten met structuralContent=true bevatten geen gevalideerde informatie en vallen daarom buiten de gebruiksvoorwaarden. Deze teksten hoef je dus niet te voorzien van een keurmerk en mag je daarom ook aanpassen.

Terug naar boven

Properties van een content object

identifier Het unieke identificatienummer van de content.
title De titel van de content.
abbreviation Afkorting van de titel van de content.
type Het contenttype van de content.
authority Organisatie die de wettelijke verantwoordelijkheid draagt voor de inhoud (strekking) van de content.
publisher De persoon of organisatie verantwoordelijk voor het publiceren van de content.
issued Datum waarop de content formeel werd vrijgegeven.
modified Datum waarop de content is gemaakt of voor het laatst inhoudelijk is gewijzigd.
dateAccepted Datum waarop de content op inhoud is gevalideerd. Deze datum kan afwijkend zijn van de datum waarop het object voor het laatst gewijzigd is (modified) of de publicatiedatum (available.start). Deze kunnen nieuwer dan dateAccepted zijn vanwege wijzigingen in de hiërarchische positie of bijvoorbeeld het corrigeren van typefouten.
available Datum waarop of periode waarin de content wordt gepubliceerd. Deze property is een object met daarin een start- en endproperty. De endproperty kan null zijn, wat betekent dat er geen einddatum bekend is.
sources Een array van bronnen (URL’s naar de bron) die aangeven op welke richtlijn/standaard/protocol de inhoud van de content is gebaseerd.
abstract Samenvatting van de content.
extent De omvang van de content uitgedrukt in het aantal woorden.
format Het formaat van de content (text/html).
subject Een array van onderwerpen van de content.
audience Een array van doelgroepen voor wie de content bedoeld of nuttig is.
language Taal waarin de content geschreven is.
languageLevel Het taalniveau waarin de content geschreven is. (Zie http://detaalbrigade.nl/taalniveaus/).
collection De contentcollectie waar de content toe behoort.
parentIdentifier De ID van de bovenliggende content. Deze eigenschap heeft de waarde NULL als het de bovenste content in de hiërarchie is.
hierarchicalOrder Een numerieke waarde die gebruikt kan worden om de volgorde van content te bepalen die dezelfde “parent” content hebben.
structuralContent Een boolean die aangeeft of de content zogeheten structuurcontent is of gevalideerde content. True = structuurcontent. False is gevalideerde content.
canonicalURL De canonical-URL van de content. Zie developers.google.com voor meer informatie.
content Een object met daarin eigenschappen van de content. De inhoud van dit object verschilt per contenttype.
content.body De HTML van de content van type “Artikel”.
content.pages Een array van objecten (pagina’s) van content van het type “Beeldverhaal”.
content.pages[.id] De unieke ID van de pagina van een beeldverhaal.
content.pages[x].title De titel van de pagina van een beeldverhaal.
content.pages[x].ImgId Het ID van de afbeelding behorende bij de pagina van een beeldverhaal.
content.pages[x].alt De alt-tekst van de afbeelding behorende bij de pagina van een beeldverhaal.
content.pages[x].audioId Het ID van het audiobestand behorende bij de pagina van een beeldverhaal.
content.pages[x].body De content (plain-text) van de pagina van een beeldverhaal.

Terug naar boven

Links in de content

De body van de content kan links bevatten naar andere content. Deze links zullen altijd in een <a> element aanwezig zijn en altijd naar de canonical URL’s van de content verwijzen. Indien de content ook op de eigen site beschikbaar is, dan kan de URL in het <a> element (de canonical-URL) eenvoudig vervangen worden door de URL waarop deze content binnen de eigen site beschikbaar is.

Indien de content waarnaar de link verwijst niet op de eigen site beschikbaar is, dan is het wellicht wenselijk om een target=”_blank” toe te voegen aan het <a>-element zodat de bezoeker niet van de eigen site verdwijnt.

Terug naar boven

Afbeeldingen en video’s in de content

Sommige content maakt gebruik van afbeeldingen en/of video’s. Deze zijn altijd omvat met een <figure> element. Indien afbeeldingen en/of video’s niet wenselijk zijn in de content op de eigen site, dan is het eenvoudig om “<figure>…</figure>” HTML-blokken te verwijderen.

De HTML-structuur van afbeeldingen en video’s is als volgt:

Terug naar boven

Afbeeldingen

<figure class="so" data-imd="123">
    <div>Titel van de afbeelding</div>
    <div>
        Bron:
        <a href="url-van-bron" target="_blank">bronvermelding met link</a>
    </div>
    <img src="https://www.opvoeden.nl/url-van-afbeelding.jpg" alt="Alt tekst">
    <figcaption>Onderschrift van de afbeelding</figcaption>
</figure>

Terug naar boven

Video’s

<figure class="so" data-video="123">
    <div>Titel van de video</div>
    <div>
        Bron:
        <a href="url-van-bron" target="_blank">bronvermelding met link</a>
    </div>
    <div>
        <iframe src="https://www.youtube-nocookie.com/url" allowfullscreen></iframe>
    </div>
    <figcaption>Onderschrift van de video</figcaption>
</figure>

Let er op dat als de afbeeldingen en/of video’s in de content op de eigen site gebruikt worden dat er dan CSS aanwezig is om de figure.so elementen de juiste vormgeving te geven. De volgende CSS kan als basis gebruikt worden. Deze CSS zorgt er tevens voor dat afbeeldingen en video’s responsive schalen.

figure.so {
	border: 1px #ddd solid;
	margin: 0 0 15px 0;
	padding: 10px;
	display: inline-block;
}

figure.so[data-video-id] {
	display: block;
}

figure.so div:first-child {
	font-size: large;
	margin: 0 0 3px;
	font-weight: 300;
	line-height: 120%;
}

figure.so div:nth-child(2) {
	font-size: small;
	margin-bottom: 10px;
}

figure.so div:nth-child(2) a {
	color: #888;
}

figure.so img {
	max-width: 100%;
	height: auto;
}

figure.so figcaption {
	font: italic small sans-serif;
	padding: 15px 3px 5px;
}

figure.so[data-video-id] div:nth-child(3) {
	position: relative;
	display: block;
	height: 0;
	padding: 0 0 56.25% 0;
	overflow: hidden;
}

figure.so[data-video-id] div:nth-child(3) iframe {
	position: absolute;
	top: 0;
	bottom: 0;
	left: 0;
	width: 100%;
	height: 100%;
	border: 0;
}

Terug naar boven

Het gebruik van beeldverhalen

Beeldverhalen kunnen op een aantal manieren gebruikt worden. De makkelijkste manier is de beeldverhalen widget, maar er kan ook gebruik worden gemaakt van de API om de data van beeldverhalen op te halen en er een eigen implementatie omheen te bouwen.

Gebruik van de beeldverhaalwidget

Om een beeldverhaal met de standaard styling te integreren in een website, zullen er twee html elementen moeten worden toegevoegd aan de website.

De head van het document

<script src="https://opvoeden.nl/plugins/beeldverhalenPlugin/public/audiobooks.js" data-styled="true"></script>

Met het attribuut data-styled=”true|false” wordt bepaald of er een generiek stylesheet wordt opgehaald, of dat de styling in eigen beheer wordt ontwikkeld. Als basis kan gebruik worden gemaakt van de generieke stylesheet, welke hier te downloaden is:

https://content.opvoedinformatie.nl/css/audiobook.css

Het is ook mogelijk om de generieke stylesheet te overrulen met eigen styles. Zorg er dan wel voor dat de eigen styles ingeladen worden na de script-tag van de widget.

De body van het document

In de body van het document kunnen meerdere beeldverhalen worden toegevoegd. Dit doe je aan de hand van de volgende code:

<div class="audiobook" id="####"></div>

De id van het html element id=”####” komt overeen met de ID van het beeldverhaal.

Terug naar boven

Contact

contact@opvoedinformatie.nl

We zijn ook bereikbaar via Twitter en te volgen via LinkedIn.