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:
- The protocol and operations supported by this API (independent of the data collection for which it is used)
- 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,... .
Field | Required | Type | Format | Description |
---|---|---|---|---|
uri | yes | string | URI | Unique identifier of the data collection |
name | no | string | Unique identifier of the data collection | |
version | no | string | Unique identifier of the data collection | |
startDate | no | date | yyyy-mm-dd | The start date of the data collection (can be in the future). As of this date, registration for this data collection can be created. |
endDateCreation | no | date | yyyy-mm-dd | The date until the registration for that data collection can be created. |
endDateSubmission | no | date | yyyy-mm-dd | The date until registrations for that data collection can be submitted. |
endDateComments | no | date | yyyy-mm-dd | Final 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.
Field | Required | Type | Description |
---|---|---|---|
id | yes | string | Unique identifier of the registration |
status | yes | string | Current status of the registration |
datacollection | no | see above | Data collection element, including at least the URI of the data collection to which this registration complies |
payload | no | string | XML/KMEHR conforming to the data collection |
createdOn | no | date | Date of creation of this registration |
updatedOn | no | date | Date 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.
Status | Description |
---|---|
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.
Field | Required | Type | Description |
---|---|---|---|
message | yes | string | The validation error |
field | no | string | (Not in v1) Closed found field in the original document where the validation error relates too |
value | no | string | (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 Operation | HTTP Request Method | Used in this API |
---|---|---|
Create | POST | yes |
Retrieve | GET | yes |
Update | PUT | not in v1, planned in v2 |
Delete | DELETE | yes |
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.