De Healthdata Registratie API biedt een system to system interface dat een 1-op1-relatie geeft met de formulieren in de user interface van HD4DP. Net zoals de user interface is de API beschikbaar via HD4DP op de infrastructuur van de instelling.
Om een goed idee te krijgen van de API zijn volgende elementen in de technische documentatie beschikbaar:
-
Het protocol en de acties mogelijk in de API (onafhankelijk van de gebruikte datacollectie)
-
De inhoud van de registratie, afhankelijk van de datacollectie waarvoor de API gebruikt wordt en de structuur van de inhoud. Zo is er een uniforme inhoud bij elke registratie.
Deze documentatie fucust op het eerste punt en geeft details over het protocol en de acties die ondersteund worden door deze API, met voorbeelden.
Belangrijk: Healthdata ondersteunt >40 datacollecties. Daarom is het protocol van de API hetzelfde voor alle datacollecties binnen healthdata.be. Het overige deel van deze documentatie neemt de variatie van de inhoud tussen de datacollecties niet in acht. Meer informatie over de inhoud van datacollecties kan gevonden worden op de website http://www.healthdata.be/dcd.
Sleutelconcepten
Datacollectie
Een datacollectie bepaalt welke data verzameld moetn worden via registraties. Voorbeelden zijn BNMDR, BCFR, IQED,... .
| Veld | Noodzakelijk | Type | Formaat | Omschrijving |
|---|
| uri | ja | string | URI | Unieke identificatie van de datacollectie |
| name | nee | string | | Unieke identificatie van de datacollectie |
| version | nee | string | | Unieke identificatie van de datacollectie |
| startDate | nee | datum | yyyy-mm-dd | De startdatum van de datacollectie (kan in de toekomst zijn). Vanaf deze datum kunnen registraties aangemaakt worden. |
| endDateCreation | nee | datum | yyyy-mm-dd | De datum tot wanneer registraties kunnen aangemaakt worden. |
| endDateSubmission | nee | datum | yyyy-mm-dd | De datum tot wanneer registraties kunnen verzonden worden. |
| endDateComments | nee | datum | yyyy-mm-dd | Einddatum, vanaf deze datum is het ongemogelijk om commentaar op verzonden registraties toe te voegen. |
Voorbeeld
Het volgende voorbeeld geeft een fictieve derde versie van het BCFR-register weer. Deze datacollectie loopt doorheen heel 20&6, maar de data providers worden een extra drie maand gegeven om registraties aan te maken en een extra maand om deze te finaliseren. Alle commentaar (bijvoorbeeld na controle door de onderzoeker) moet behandeld worden voor het eind van juni 2017. Nadien wordt het onmogelijk om aanpassingen door te voeren.
<datacollection>
<uri>https://catalogue.healthdata.be/healthdata_catalogue/datacollectiondefinitions/2761</uri>
<name>BCFR</name>
<version>3</version>
<startDate>2016-01-01</startDate>
<endDateCreation>2017-03-31</endDateCreation>
<endDateSubmission>2017-04-30</endDateSubmission>
<endDateComments>2017-06-30</endDateComments>
</datacollection>
Registratie
Een registratie is een set van data dat beantwoordt aan de vragen van een datacollectie. In de user interface is dit een formulier.
| Veld | Noodzakelijk | Type | Description |
|---|
| id | ja | string | Unieke identificatie van de registratie |
| status | ja | string | Huidige status van de registratie |
| datacollection | nee | zie boven | Datacollectie-element, inclusief het laatste URI van de datacollectie voor dee registratie |
| payload | nee | string | XML/KMEHR volgens de datacollectie |
| createdOn | nee | datum | Datum van de creation van deze registration |
| updatedOn | nee | datum | Datum van de laatste aanpassing van deze registratie |
Statussen
De volgende lijst is een complete lijst van statussen die een registratie kan hebben in HD4DP, vanaf versie 1.7. In de toekomst kan deze lijst nog veranderd worden.
| Status | Omschrijving |
|---|
| IN_PROGRESS | |
| SUBMITTED | |
| UNAUTHORIZED | |
| ACTION_NEEDED | |
| DELETED | |
| OUTBOX | |
| APPROVED | |
Voorbeeld
<registration>
<id>1234</id>
<status>IN_PROGRESS</status>
<datacollection>
<uri>https://catalogue.healthdata.be/healthdata_catalogue/datacollectiondefinitions/2761</uri>
<name>BCFR</name>
</datacollection>
<createdOn>2014-01-01T00:00:00Z</createdOn>
<updatedOn>2014-01-02T14:36:12Z</updatedOn>
</registration>
Validatiefout
Naar de applicatiefouten (zie onderaan) kunnen er ook validatiefouten ontstaan. Deze fouten kunnen gegeven worden door de API. In versie 1 van de API zal enkel de foutboodschap gegeven worden.
| Veld | Noodzakelijk | Type | Omschrijving |
|---|
| message | ja | string | De validatiefout |
| field | nee | string | (Niet in v1) Het veld in het document waarop de foutboodschap wijst |
| value | nee | string | (Niet in v1) De waarde van het veld |
Indien er een fout is op één veld zal de boodschap ze uitzien als dit voorbeeld:
<validation-error>
<field>
<location>44071154303/deathdate</location>
<value>null</value>
</field>
<message>is a required field</message>
</validation-error>
Indien de foutboodschap slaat op meerdere velden zal de boodschap er uitzien zoals onderstaand voorbeeld:
<validation-error>
<field>
<location>44071154303/deathdate</location>
<value>2015-05-20</value>
</field>
<field>
<location>44071154303/birthdate</location>
<value>2015-01-20</value>
</field>
<message>deathdate can't be before birthdate</message>
</validation-error>
REST based API
Deze API gebruikt de basisprincipes van REST. De volgende tabel geeft een overzicht van de CRUD-acties en bijhorende HTTP Request Methods en het gebruik ervan.
| CRUD Operatie | HTTP Request Method | Gebruikt in deze API |
|---|
| Create | POST | ja |
| Retrieve | GET | ja |
| Update | PUT | niet in v1, gepland voor v2 |
| Delete | DELETE | ja |
Media Types
REST APIs kunnen verschillende mediatypes verwerken (json, XML, atom, ...). Deze API (v1) gebruikt XML als mediatype. Binnenin de data verwacht de API KMEHR data. Voor meer informatie over dit type, zie de bijhorende datacollectie.
API Endpoint
De API wordt aangeboden via HD4DP, dat geïnstalleerd is op de infrastructuur van de data provider, volgens de Healthdatavoorwaarden, zoals goedgebeurd door de eHealth architectuurgroep.
Deze methode zorgt ervoor dat data providers snelle toegang hebben tot de API en functionaliteiten zonder zorgen hoeven te maken over overhead of operationele noden naar een externe dienst zoals eHealth of healthdata.be
HTTP vs HTTPS
Het is aan de data provider om te kiezen voor https op HD4DP. Het certificaat moet gelijk zijn aan de domeinnaam, of de API moet ingesteld worden om self-signed certificates te gebruiken.
Authenticatie
De API gebruikt OAuth voor authenticatie and authorisatie. Ditzelfde mechanisme wordt gebruikt in HD4DP. Gebruik maken van de bestaande LDAP of data provider is mogelijk.
Status van foutmeldingen
De standaard HTTP Response Status Codes worden gebruikt.
Verwachte HTTP Response status codes voor de API:
-
200 OK - Succesvolle request
-
201 Created - Registratie aangemaakt
-
204 No Content - Registratie verwijderd
-
400 Bad Request - Registratie is NIET aangemaakt door een foute request
-
403 Forbidden - De gebruiker heeft geen toelating tot deze registratie
-
404 Not Found - Registratie niet gevonden (fout id)
-
409 Conflict - Registratie NIET aangemaakt door een validatiefout of door verkeerde datacollectie
-
422 Unprocessable Entity – Wordt gebruikt indien de server iets niet kan verwerken, zoals bijvoorbeeld een afbeelding die niet gebruikt kan worden of een verplicht veld dat niet ingevuld werd.
