The HD4DP v2 S2S API is a unified Application Programming Interface (API) that will allow participating Healthcare Organizations (HCO) to submit DCDs data to HD4DP2.0 fully automated. In the manual of the application HD4DP v2 we provide detailed information about the S2S API:
- End-to-End process to submit DCD registrations
- API Endpoint for supporting the DCD submit process
- API Endpoint for searches DCD registrations
- MDM Field description - DB Model
- Swagger API
Important note: For code fields (fieldType = 'CODE') the id of the codeListValue item must be sent, not the code value or the label. In future releases it will be made possible to also send the code value.
Please read this documentation before its project specific use.
API description
API end-point | Response | Authentication | Notes |
---|---|---|---|
/api/organizations | List of organizations. Client must select the right organizationId | No | Current existing end-point is: /api/installation/organizations We’ll create this new end-point with a different signature re-routing the call to this existing one or we will refactor the existing one to this new signature. |
/api/dcd/menu/structure? organization-id={organizationId} | List of projects of the given organization, dcds of each project, dcdVersions of each dcd in a JSON format Client can get dcdId and dcdVersionId (optional) which are needed on following API calls. | No | https://github.com/Sciensano-Healthdata/hd4-formio/blob/develop/dev/mock_menu_structure/menu-structure.json |
/api/dcd/payload/definition? dcd-id={dcdId}; <optional>version={version}; <optional>language-id={languageId} | List of all the fields of the form as well as their corresponding data-types that are allowed in the json data structure for the Payload | Yes | This field names values are the key properties in the formIO json config form. When we implement this new api end-point, we need to parse the json content in order to get the key properties. Given these field keys, we’ll get each field definition from new API end-points helpers: /api/dcd/field?field-id={fieldId} /api/dcd/codelist?codelist-id={codelistId} These ones are described in the next table. <optional parameter> version={version} : If this parameter is not provided, latest one is assumed <optional parameter> language-id = {languageId} : language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values: en: English nl: Dutch fr: French Client must build this json object as the payload data to be sent based on this list of fields, on the last api call |
/api/dcd/payload/example?dcd-id={dcdId}; <optional>version={version} | Example of payload in JSON format | Yes | Providing this API end-point in order to help the Client on the Payload build with an example <optional parameter> version={version} : If this parameter is not provided, latest one is assumed |
/api/dcd/payload/submit? organization-id={organizationId}; dcd-id={dcdId}; <optional>version={version}; <optional>data-src-type={dataSrcType}; POST Payload | Results info if succeed Error info if failed | Yes | Some implementation tasks is needed in here in order to return the result info (either succeed or failed). Similar like the one in HDConnectProxyRestTemplate.postCsv method, and the CsvExecutionResult object build. <optional parameter> version={version} : If this parameter is not provided, latest one is assumed. <optional parameter> data-src-type={dataSrcType} : permitted values: API CSV If this parameter is not provided, default values is <HD4DP>. |
api/dcd/payload/submit?organization-id={organizationtId};dcd-id={dcd-id};<optional>dcd-version-id={dcdVersionId};<optional>incl-submit-data={inclSubmitData}; <optional>incl-submit-results={inclSubmitResults}; GET method | List of submitted dcds data and/or their corresponding business keys or validation errors. | Yes | <optional parameter> dcd-version-id={dcdVersionId} : If this parameter is not provided, lastest one is assumed <optional parameter> incl-submit-data={inclSubmitData} : If this parameter is not provided, default values is <false> <optional parameter> incl-submit-results={inclSubmitResults} : If this parameter is not provided, default values is <true> |
Get organizations
Request example
GET /api/organizations
Request response
[
{
"organizationId": 1,
"organizationCode":"12345",
"name":"First Organization Name",
"loginMethods":[
"USERNAME_PASSWORD",
"EID"
]
},
{
"organizationId": 2,
"organizationCode":"32154",
"name":"Second Organization Name",
"loginMethods":[
"EID"
]
}
]
Get the DCD menu structure
Request example
GET /api/dcd/menu/structure?organization-id={organizationId}
Request parameters
- {organizationtId}: Id of the organization for which we want to list the menu structure
Request response
All the menu structure for that organization, including projects, dcds of each project and dcd versions of each dcd, in a JSON format.
[
{
"id": 4,
"key": "zephyr_pneumo_program",
"projects": [
{
"id": 4,
"key": "zephyr_pneumo_project",
"dcds": [{
"id": 9,
"key": "zephyr_pneumo_t1_dcd",
"dcdVersions": [{
"id": 9,
"version": 1,
"supportsEN": false,
"supportsFR": true,
"supportsNL": true
}]
},
{
"id": 10,
"key": "zephyr_pneumo_tr_dcd",
"dcdVersions": [{
"id": 10,
"version": 1,
"supportsEN": false,
"supportsFR": true,
"supportsNL": true
}]
},
. . .
. . .
. . .
. . .
]
Get DCD field definitions
Request example
GET /api/dcd/payload/definition?dcd-id={dcdId};version={version};language-id={languagerId}
Request parameters
- {dcdId}: Id of the dcd
- <optional parameter> {version}: If this parameter is not provided, latest one is assumed
- <optional parameter> {languageId}: language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values:
- en: English
- nl: Dutch
- fr: French
Request response
{
"CD_SURGL_APPR_FEMO": {
"field_type": "CODE",
"data_type": "number",
"code_list": [
{
"ID": 68224,
"CODE_VALUE": "870646003",
"LABEL_EN": "Femoral (Hemi)"
},
{
"ID": 68225,
"CODE_VALUE": "465954006",
"LABEL_EN": "Femoral + Cup"
}
]
},
"D_IMPLANT": {
"field_type": "DATE",
"data_type": "timestamp",
"code_list": null
},
"TX_TPE_INSTRU": {
"field_type": "FREE TEXT",
"data_type": "string",
"code_list": null
},
"MS_PAT_HGHT": {
"field_type": "FREE TEXT",
"data_type": "number",
"code_list": null
}
}
Get DCD payload example
Request example
GET /api/dcd/payload/example?dcd-id={dcdId};version={version}
Request parameters
- {dcdId}: Id of the dcd
- <optional parameter> {version}: If this parameter is not provided, latest one is assumed
Request response
Given the previous Payload field definition example on previous chapter, we build a payload content example accordingly.
{
"CD_SURGL_APPR_FEMO": 68224,
"D_IMPLANT": "2021-04-30T22:00:00",
"TX_TPE_INSTRU": "P-432",
"MS_PAT_HGHT": 180
}
Submit DCD registrations
Request example
POST /api/dcd/payload/submit?organization-id={organizationId};dcd-id={dcdId};version={version};data-src-type={dataSrcType}
Header:
MediaType.APPLICATION_JSON
Body:
{
{
"CD_SURGL_APPR_FEMO": 68224,
"D_IMPLANT": "2021-04-30T22:00:00",
"TX_TPE_INSTRU": "P-432",
"MS_PAT_HGHT": 180
},
{
"CD_SURGL_APPR_FEMO": 68225,
"D_IMPLANT": "2021-04-14T22:00:00",
"TX_TPE_INSTRU": "P-545",
"MS_PAT_HGHT": 1209
},
{
"CD_SURGL_APPR_FEMO": 68224,
"D_IMPLANT": "2021-05-01T22:00:00",
"TX_TPE_INSTRU": "T-678",
"MS_PAT_HGHT": 210
}
}
Request parameters
- {organizationtId}: Id of the organization for which we want to submit the DCD registration.
- {dcdId}: Id of the DCD we want to submit.
- <optional parameter> {version}: Id of the DCD Version we want to submit. If this parameter is not provided, latest one is assumed.
- <optional parameter> {dataSrcType}: The data source type e.g: API or CSV.
Request payload
- {Header}: MediaType.APPLICATION_JSON
- {Body}: JSON object with an array of DCDs data to be submitted, following the specifications and examples provided by the described api end-points:
- GET /api/dcd/payload/definition
- GET /api/dcd/payload/example
Request response
Client get a response per each DCD line. If the DCD submission was successful, Client will get a TXT_BUSINESS_KEY value. If it was failed, Client will get an error detailed info: Http Status Code, Name and Exception details:
{
"TX_BUSINESS_KEY": "NISS 12.06.01-052.46 30/04/2021 67864",
{
"HTTP_STATUS_CODE": 405,
"HTTP_STATUS_NAME": "Method Not Allowed",
"HTTP_STATUS_EXCEPTION_DETAILS": "Exception details for Method Not Allowed example",
},
"TX_BUSINESS_KEY": "NISS 12.06.01-071.48 01/05/2021 67864",
}
User / password
The username and password can be requested at our Servicedesk.