docs.healthdata.beTable of contents
- API description
- Get organizations
- Get the DCD menu structure
- Get DCD field definitions
- Get DCD payload example
- Submit DCD registrations
- User password
- Submission of drafts
- Adding separators to a NISS number
API description
The baseURL to be used has to following built: https://<hd4dp_url>/proxy
| API end-point | Response | Authentication | Notes |
|---|---|---|---|
| {{baseURL}}/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. |
| {{baseURL}}/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 |
| {{baseURL}}/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 |
| {{baseURL}}/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 |
| {{baseURL}}/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>. |
| {{baseURL}}/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 {{baseURL}}/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 {{baseURL}}/api/dcd/menu/structure?organization-id={organizationId}
Request parameters
- {organizationtId}: Id of the organization for which we want to list the menu structure
- {{baseURL}}: the value for this field is https://<hd4dp_url>/proxy
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 {{baseURL}}/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 {{baseURL}}/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 {{baseURL}}/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.
Submission of drafts
To submit a draft, the only thing to add is the key STATUS (all upper case) with the value "draft" to the request, like this:
"STATUS": "draft",
If the status is sent as "draft", a draft registration is created. In case of a successful submission the user receives a HTTP 202 (Accepted) notification with an empty business key, like this:
If the status key is not sent, the default value "submit" is used. The user performs a complete submission, and in case of a successful submission the user receives a HTTP 202 (Accepted) notification with a business key, like this:
Note that only "draft" status needs to be sent when sending a draft. The status "submit" is not necessary when performing a complete submission.
In the GUI, the difference is that the draft submission has the status open while the complete submission has the status submitted:
Once the draft is submitted in the GUI, the business key is generated and the process completed.
Adding separators to a NISS number
It is not necessary to add separators in a NISS number when uploading a file using S2S API. You can fill the NISS number out both with or without seperators. E.g.: 85.04.02-169.32 or 85040216932.
