Registration API

The Healthdata Registration API provides a system to system interface

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

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.

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.

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.

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.

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.