Reset Search
 
Article

Registration API

« Go Back

Support article

 
Last Modified Date5/5/2017 11:29 AM
SummaryThe Healthdata Registration API provides a system to system interface
Content

The Healthdata Registration API provides a system to system interface that matches the forms provided through the user interface of HD4DP. Just like the user interface, the Healthdata Registration API is exposed through HD4DP, installed on the data provider's infrastructure.

To provide a good understanding of the Healthdata Registration API, the following aspects are covered in the technical documentation:

  1. The protocol and operations supported by this API (independent of the data collection for which it is used)

  2. The registration content, dependent on the data collection for which the API is used and the content semantics, enabling a content-wise harmonisation across the registration content.

This documentation focuses on the 1st point and provides the details of the protocol and operations supported by this API, as well as examples and mock services.

Important: Healthdata will support >40 data collections. Therefore, the protocol layer of the API is the same for all of the data collections on healthdata.be. The remainder of this documentation will not take into account the variation of content between the different data collections. More information about the content of the data collections can be found on the healthdata website http://www.healthdata.be/dcd.
 

Key Concepts

Data Collection

A data collection defines the data that is collected through registrations. Examples are BNMDR, BCFR, IQED,... .

FieldRequiredTypeFormatDescription
uriyesstringURIUnique identifier of the data collection
namenostring Unique identifier of the data collection
versionnostring Unique identifier of the data collection
startDatenodateyyyy-mm-ddThe start date of the data collection (can be in the future). As of this date, registration for this data collection can be created.
endDateCreationnodateyyyy-mm-ddThe date until the registration for that data collection can be created.
endDateSubmissionnodateyyyy-mm-ddThe date until registrations for that data collection can be submitted.
endDateCommentsnodateyyyy-mm-ddFinal end date, at which it becomes impossible to add comments on already previously submitted data collections.
 

Example

The following example represents the fictitious example the 3rd version of the BCFR data collection. This data collection runs throughout 2016, but data providers are given 3 extra months to create registrations and another additional month to finalize them. All comments (e.g., after validation by the researcher) need to be handled by the end of june 2017, after which it becomes imposible to make further changes.

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

Registration

A registration is a set of data that corresponds to the data collection. In the user interface, this corresponds to a form.

FieldRequiredTypeDescription
idyesstringUnique identifier of the registration
statusyesstringCurrent status of the registration
datacollectionnosee aboveData collection element, including at least the URI of the data collection to which this registration complies
payloadnostringXML/KMEHR conforming to the data collection
createdOnnodateDate of creation of this registration
updatedOnnodateDate of last change of this registration
 

Statuses

The following is a complete list of statuses that a registration can have in HD4DP as of version 1.7. Note that in future versions this list might change.

StatusDescription
IN_PROGRESS 
SUBMITTED 
UNAUTHORIZED 
ACTION_NEEDED 
DELETED 
OUTBOX 
APPROVED 
 

Example

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

 

Validation Error

Apart from application errors (see Error States below) validation errors at content level can occur. These errors will be returned to the API client with the following information. In version 1 of the API, only the message field will be included.

FieldRequiredTypeDescription
messageyesstringThe validation error
fieldnostring(Not in v1) Closed found field in the original document where the validation error relates too
valuenostring(Not in v1) The value parsed from the field

If an error applies to 1 field (intrafield error, e.g., a missing required field), the error will look like the following example:

<validation-error>
    <field>
        <location>44071154303/deathdate</location>
        <value>null</value>
    </field>
    <message>is a required field</message>
</validation-error>

If the error occurs due to an interplay of several fields (interfield error, e.g., the sum of field A and B is larger than a threshold), the error will look like the following example, where the cardinality of field = n

<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

This API uses the base design principles of REST. The following table gives an overview of the CRUD actions and the corresponding HTTP Request Methods, as well as an indication of their usage.

CRUD OperationHTTP Request MethodUsed in this API
CreatePOSTyes
RetrieveGETyes
UpdatePUTnot in v1, planned in v2
DeleteDELETEyes
 

Media Types

REST APIs can handle with various media-types (json, XML, atom, ...). For this API (v1), XML will be used as media-type. Within the payload, this API expects KMEHR compatible content. For more information on the content of the payload, see the applicable data collection

 

API Endpoint

The API is exposed through HD4DP, which is installed on the infrastructure of the data provider, according to the healthdata architecture as approved by the eHealth architecture group.

This approach enables the data providers to have a very fast access to the API functionality without any network overhead or operational requirements on external service such as eHealth or healthdata.be

 

HTTP vs HTTPS

It is up to the data provider to activate https on HD4DP. The certificate should match the domain used or the API client should be able to deal with self-signed certificates.

 

Authentication

The API uses OAuth for authentication and authorization. This is the same authentication mechanism as used within HD4DP. Linking the existing LDAP of the data provider is possible.

 

Error States

The common HTTP Response Status Codes are used.

Expected HTTP Response status codes for this API:

  • 200 OK - Request successfully processed

  • 201 Created - Registration created

  • 204 No Content - Registration removed

  • 400 Bad Request - Registration is NOT created due to a malformed request

  • 403 Forbidden - User is not allowed to access registration

  • 404 Not Found - Registration not found (wrong id given)

  • 409 Conflict - Registration NOT created due to validation errors or because an invalid data collection is used

  • 422 Unprocessable Entity – Should be used if the server cannot process the entity, e.g., if an image cannot be formatted or mandatory fields are missing in the payload.

Feedback

 

Was this article helpful?


   

Feedback

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

Characters Remaining: 255