REST API
Central Platform provides several APIs which facilitate common logic for on premise products like Unified Messaging, Hector and HealthConvex. Next to these products we also have integrators who make use of some of these endpoints.
Work in progress: on the 'integrate' page more in-depth information concerning the APIs and how to integrate with them is given.
CCC
Command and Control Configuration (CCC) is a tool which aims to make the life of our support people better. A wide variety of support functionality is provided here.
Searching for Hector/UM/HealthConvEx installations
Here you can search for installations and retrieve their (summary) configuration. An installation can be found given the installation id, application, version and/or careprovider
Unified Messaging Licenses
You can create, update and revoke licenses for unified messaging. A license is bound to the machine id on which the unified messaging prouct has been installed upon.
Manage integrators
You can add and remove integrators who integrate on our external systems. We always prefer to register software as an integrator and not our customers. Logins for customers are only allowed when they perform
Assurmed
Management endpoints are provided to configure insurers on Assurmed.
HealthPages
Here you can quickly look up a healthcare provider. The search is delegated to HealthPages and the response is transformed. Only active contacts from HealthPages are searchable.
Security
Basic authentication
Some of our endpoints are secured using HTTP Basic authentication. Most integrators are given such a login upon request.
Bearer authentication
Most of our REST endpoints are secured using HTTP Bearer tokens. We accept tokens which are issued by Accounts. Most integrators should use a token issued by Accounts.
Contact HealthConnect in case of doubt.
Accounts
For more information see https://accounts.healthconnect.be/docs/
REST principles
Our APIs are (all debates aside) restful APIs. The HTTP verbs GET, POST, PUT and DELETE are used to implement ‘CRUD’ operations on our resource endpoints.
Unless otherwise indicated, our APIs will always consume and return JSON and only JSON.
Response codes
To indicate the outcome of a request, we use the HTTP status codes. In case of an error, the body contains an extra code giving more details. The caller can use the HTTP status code for basic branching, and the code in the body for actually interpreting the result. An error code in the body will always be returned using the same HTTP status code.
Success
Successful requests return or a 200 OK, a 201 Created or a 204 No Content.
Errors
As for error codes, we follow the standard categories of 4xx Client errors and 5xx Server errors. A response with a 4xx or 5xx code will always contain a response body following a fixed template.
code |
A code giving more details about the actual error |
Required |
message |
A message with some more details about the origin and cause of the error. This is done on a best effort basis. This message is user friendly. |
Required |
description |
A more detailed description of the problem and what can be done to solve it. This messsage is developer oriented. |
Optional |
uniqueId |
Given that id, we can find the root cause of the problem more easily in our logs. Integrators are required to pass this id when asking for details about a failed call. |
Optional |
stacktrace |
Depending on the environment and availability, we will return a stacktrace. |
Optional |
{
"code":"internal_server_error",
"message":"An unknown error has occurred.",
"description":"The reason and origin of this error cannot be processed automatically. Contact support to further investigate this problem. Do not forget to pass the unique id returned in the response.",
"uniqueId":"d84d49e2fb5548a8956540f778b79f50",
"stacktrace":"..."
}There are three groups of errors: validation errors, client errors and server errors.
Validation errors
This kind of error is always returned with the HTTP status code 422 Unprocessable Entity.
Besides the usual error fields, this error contains an extra field validationErrors.
The object assigned to that field contains three extra field being:
-
The field that contains the validation error
-
The error message indicating the problem
-
The value that triggered the validation violation
{
"code":"input_validation_error",
"message":"The input contains validation errors.",
"description":"Check the error messages contained in this response to correct your input and try again. This error is entirely related to your input. Do not retry without changing the input.",
"uniqueId":"a6399b01e8294162be4f4f914b353a4b",
"validationErrors":[
{
"field":"name",
"value":null,
"message":"Request is missing fields. Consult the documentation for details on how to build the request."
},
{
"field":"identifier",
"value":null,
"message":"may not be null"
},
{
"field":"lastName",
"value":null,
"message":"Request is missing fields. Consult the documentation for details on how to build the request."
},
{
"field":"firstName",
"value":null,
"message":"Request is missing fields. Consult the documentation for details on how to build the request."
}
]
}Client errors
All errors in the 4xx range are client errors.
We use the following non-exhaustive list of status codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 415 Unsupported Media Type, 422 Unprocessable Entity, etc.
Server errors
A server error is returned as either a 500 Internal Server Error, 502 Bad Gateway or a 503 Service Unavailable.
Pagination
Some of our endpoints support pagination. This is implemented using a combination of query parameters and a predefined response body.
Every resource endpoint that supports paging, accepts a page parameter and a size parameter.
https://healthservices.corilus.be/api/credentials?page=1&size=10
In the response for that request, the actual content is wrapped in a predefined body.
{
"pageable": {
"page": 1,
"size": 10
},
"page": {
"totalCount": "83",
"hasMore": "true",
"content": [ { ... }, { ... }, ... ]
}
}Locale
Every request requires a locale.
This locale must be set via the Accept-Language header.
Acceptable values are en-BE, fr-BE and nl-BE.
The results returned by our services are based on and oriented towards the given locale.
For instance labels and descriptions will be set accordingly.
User-Agent
Every request requires a user agent.
This user agent must be set via the User-Agent HTTP header.
The user agent is used in our back-end systems for logging purposes and selecting the correct licenses to other backend systems.
We highly recommend passing the name of your product as user agent as this makes functionally the most sense.
When interpreting the User-Agent HTTP Header we apply the following regular expression for validation: [A-Za-z0-9-]{3,128}/[A-Z0-9.-]{1,64}
Your user agent will only be accepted if it matches this pattern!
Example of a correct User-Agents: MyProductName/3.11.7
Strings
Unless otherwise specified, our string-values are always UTF-8 encoded.
| If you want to avoid issues related to encoding, ensure that your string-values are UTF-8 encoded when your provide them to our system. |
Timezones
Our system is internally configured to run on the Europe/Brussels timezone. When we communicate timestamps without a timezone it will respect this timezone.
In any other case, you must interpret the timezone to the timestamp.