Reset Search
 
Artikel

Registratie-API

Support article

 
Datum van laatste wijziging22-5-2017 7:24
OverzichtRegistratie-API
Content

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:

  1. Het protocol en de acties mogelijk in de API (onafhankelijk van de gebruikte datacollectie)

  2. 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,... .

VeldNoodzakelijkTypeFormaatOmschrijving
urijastringURIUnieke identificatie van de datacollectie
nameneestring Unieke identificatie van de datacollectie
versionneestring Unieke identificatie van de datacollectie
startDateneedatumyyyy-mm-ddDe startdatum van de datacollectie (kan in de toekomst zijn). Vanaf deze datum kunnen registraties aangemaakt worden.
endDateCreationneedatumyyyy-mm-ddDe datum tot wanneer registraties kunnen aangemaakt worden.
endDateSubmissionneedatumyyyy-mm-ddDe datum tot wanneer registraties kunnen verzonden worden.
endDateCommentsneedatumyyyy-mm-ddEinddatum, 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.

VeldNoodzakelijkTypeDescription
idjastringUnieke identificatie van de registratie
statusjastringHuidige status van de registratie
datacollectionneezie bovenDatacollectie-element, inclusief het laatste URI van de datacollectie voor dee registratie
payloadneestringXML/KMEHR volgens de datacollectie
createdOnneedatumDatum van de creation van deze registration
updatedOnneedatumDatum 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.

StatusOmschrijving
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.

VeldNoodzakelijkTypeOmschrijving
messagejastringDe validatiefout
fieldneestring(Niet in v1) Het veld in het document waarop de foutboodschap wijst
valueneestring(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 OperatieHTTP Request MethodGebruikt in deze API
CreatePOSTja
RetrieveGETja
UpdatePUTniet in v1, gepland voor v2
DeleteDELETEja
 

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.

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255