API Opzet

De HOVI API gaat uit van de volgende basisprincipes:

REST API: OpenAPI, JSON
Naamgeving: lowercase in routes (URLs), camelCaps in JSON data, engels
Zo opgezet dat spec wijzigingen bij extra uitvoertaal minimaal zijn
Instellingen kunnen geen IDs voor nieuwe entiteiten kiezen, maar kunnen koppelingen voor intern gebruik in een veld (userKey) opslaan. Omdat we dan deze IDs globaal uniek kunnen maken kunnen we dan ook eenvoudig referenties naar opleidingen van andere instellingen aan laten maken als dit nodig blijkt te zijn.

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

Alleen gebruikers gemarkeerd als afnemers kunnen feedback plaatsen
Schrijfrechten kunnen per organisatie beperkt worden (/organisation/{organisationID}/ route en dieper)
Organisaties kunnen alleen aan hen gerichte feedback via de API opvragen

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

Velden die als alleen-lezen zijn gemarkeerd kunnen worden opgestuurd naar de API, maar worden niet weggeschreven (de velden 'programId' en 'organisation' kunnen bijvoorbeeld niet via een POST of PUT worden gewijzigd).
De API neemt alleen volledige documenten aan, er is geen manier om alleen paar velden te wijzigen. Dit kan gedaan worden door een GET te doen van het document, de alleen-lezen velden te verwijderen, de gewenste wijzigingen aan het document te doen en dan een PUT te doen (de uitzondering is voor de velden 'croho' en 'programType' van producten, die kunnen via een PATCH operatie worden aangepast).
Bij GET, PUT en POST verzoeken wordt het gehele document teruggegeven, met een ETag. Deze kan met de 'If-Match' header worden doorgegeven aan een PUT om te voorkomen dat tussentijdse wijzigingen verloren gaan.
Het formaat van de datum-en tijdvelden in de API zijn conform de ISO-8601 standaard.

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 < worden opgestuurd, en & als &. Karakters als numerieke ‘entities’ doorgeven mag ook, bv: &

De volgende HTML tags mogen gebruikt worden:

voor paragrafen
<ul> voor lijsten (en dus binnen de <ul> tag 1 of meer <li> tags)

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 ‘’, ‘’ 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 Hello™€ opstuurt tellen wij 7 karakters voor de maximum-lengte controle en krijgt men bij het opvragen van het veld de waarde Hello™€ terug.

Lege paragrafen en lijstregels worden bij normalisatie ook verwijderd.

Feedback

Feedback is zeer welkom en mag naar info@hovi.nl worden gestuurd.