API Opzet

De HOVI API gaat uit van de volgende basisprincipes:

Afnemers en instellingen gebruiken dezelfde API maar de volgende rechtenbeperkingen zijn mogelijk:

De API dwingt geen verdere rechtenbeperkingen binnen organisaties af - schrijf- en publicatierechten per opleiding worden in de HOVI Editor zelf geimplementeerd of moeten door de instellingen zelf in hun eigen koppelingen ingeregeld worden.

Een API gebruiker kan meerdere API sleutels tegelijk in gebruik hebben (bv. voor sleutelrotatie).

Aan de slag met de API

De eerste stap is het verkrijgen van een API sleutel. Dit kan door een e-mail te sturen naar info@hovi.nl. Geef hierbij aan voor welke instelling u toegang wenst, of dat u afnemer wilt worden.

Met de API sleutel u verstrekt wordt kunt u vervolgens API calls maken. Het huidige OpenAPI 3.0 document dat de API beschrijft kunt u hier vinden. Een testclient voor deze API kunt u hier vinden, u kunt daar uw API sleutel invullen om te testen. 

Om op te letten

Rich text velden

Sommige velden zijn in het datamodel beschreven als richtext. Richtext data is gedefinieerd als een subset van HTML. De rich text dient uit paragrafen en/of ongenummerde lijsten te bestaan, en mag verder alleen bold, italics en soft breaks bevatten. Daarnaast dienen speciale karakters geescapet te worden als HTML entities: dus < moet als &lt; worden opgestuurd, en & als &amp;. Karakters als numerieke ‘entities’ doorgeven mag ook, bv: &#38;

De volgende HTML tags mogen gebruikt worden:

Daarnaast moet de rich text met een tag beginnen, zodat we zeker weten dat de API gebruiker zich realiseert dat het veld rich text bevat. Afnemers zullen dus ook altijd HTML zien in de afgenomen velden en zullen dus niet zonder nabewerking deze velden als gewone tekst kunnen overnemen. Zo weten we zeker dat men niet eenvoudig een veld kan ‘vergeten’.

De database ‘normaliseert’ de ontvangen HTML code zodat deze altijd aan bovenstaande structuur voldoet en afnemers er vanuit kunnen gaan dat de rich text altijd dezelfde structuur heeft (en deze eenvoudig kunnen stijlen). Afnemers kunnen er dus vanuit gaan dat er geen onverwachte ‘<span>’, ‘<strong>’ of ‘style=’ in de rich text zal staan. Wel is het natuurlijk mogelijk dat nieuwe releases van de HOVI spec de set van toegestane tags aanpassen.

Bij het controleren van de maximum lengte van een rich text veld wordt gekeken naar het aantal unicode karakters (‘codepunten’) en wordt de HTML genegeerd. Wel geldt er vooralsnog een absolute grens van 2047 bytes voor de volledige inhoud inclusief HTML (na normalisatie en UTF-8 codering). 

Om een voorbeeld te geven: als je de waarde <P class=”normal">Hello™&euro; opstuurt tellen wij 7 karakters voor de maximum-lengte controle en krijgt men bij het opvragen van het veld de waarde <p>Hello™€</p> terug.

Lege paragrafen en lijstregels worden bij normalisatie ook verwijderd.

Feedback