FHIR API overview
The FHIR API enables integrators to interact with practice databases using the HL7® FHIR® standard.
This page assumes you have already read the Halo Cloud overview.
FHIR® is the registered trademark of HL7 and is used with the permission of HL7. Use of the FHIR trademark does not constitute endorsement of the contents of this repository by HL7.
Supported PMS
The FHIR API currently supports:
Architecture
The FHIR API is a FHIR facade, not a full FHIR server. See Edenlab's article on FHIR facades for an explanation of the pros and cons. This means that FHIR queries sent to Halo Cloud get translated into SQL by Halo Link's FHIR translation engine which is run on the practice's database, then the result is translated back into FHIR.
sequenceDiagram
participant I as Integrator
participant HC as Halo Cloud
box Halo Link
participant HL as Halo Link agent
participant FE as FHIR engine
end
participant PD as PMS database
I-->>+HC: Send FHIR request
HC-->>+HL: Forward FHIR request
HL-->>+FE: Forward FHIR request
FE-->>+PD: Execute query as SQL
PD-->>-FE: Return SQL result
FE-->>-HL: Return FHIR result
HL-->>-HC: Forward FHIR result
HC-->>-I: Forward FHIR resultFHIR version
The FHIR API is currently based on:
- FHIR Release 4 (R4) version 4.0.1
- AU Base Implementation Guide version 4.1.0 (where applicable)
Authentication and authorisation
Halo Cloud authentication
As with any Halo Cloud API, authentication with Halo Cloud requires a Halo Cloud subscription.
PMS database authorisation
Halo Connect does not handle PMS database access authorisation. What data integrators can access is managed by the respective PMS provider. For this reason, using Halo APIs requires integrators to have onboarded with the relevant PMS and for database credentials to have been created for the integrator's access requirements.
For the FHIR API, integrators will need database credentials which give them access to the database tables required for each FHIR resource they wish to use. Contact the relevant PMS provider if you require changes to your access.
Sending FHIR requests
Requests
FHIR requests are sent as standard HTTP requests. Integrators will need to know the base url for the API environment they wish to use (staging or production) and the Halo GUID for the practice they wish to query. For example, to request the Patient resource with ID pt-1, the query would be:
GET {{baseUrl}}/Patient/pt-1
The API base URL can be found in Getting started with Halo Cloud.
FHIR API is case sensitive
Please note the FHIR API's URI is case sensitive. This applies to both the base URI (e.g. R4 must be capitalised) and parameters (e.g. _lastUpdated must have a capital U).
More information about routing queries by Halo GUID can be found in the Halo Cloud overview.
Results
Successful query results are delivered embedded in a JSON response, formatted per the FHIR specification. Data will be returned as either a singular resource or as a Bundle containing multiple resources.
Errors will be returned as an OperationOutcome resource.
Pagination is also implemented per the FHIR specification for search result paging.
Limitations
The FHIR API does not implement every feature of FHIR. Please see the Capabilities page for high-level information about what functionality is available, and how to check the Capability Statement for more details.
The FHIR API uses immediate query infrastructure under the hood. The limitations which apply to immediate queries also apply to FHIR requests.
Timezones
Due to limitations in what data Halo Link has access to, datetime data is represented using the timezone of the server Halo Link is installed on. If a server serves multiple practices from multiple timezones, datetimes for all practices will be given as the server timezone.
Third-party artifacts and terminologies
The FHIR API uses and references intellectual property owned by third parties ("Third Party IP"), such as terminologies used in resource data. Acceptance of the License Terms for Halo Connect products does not grant any rights with respect to Third Party IP. The licensee is responsible for identifying and obtaining any necessary licenses or authorisations to utilise Third Party IP.
The following is a non-exhaustive list of third-party artifacts and terminologies used by the FHIR API which may require a separate license:
| Artifact/Terminology | More info |
|---|---|
| Australian National Clinical Terminology Service | See NCTS Licensing. |
| SNOMED CT | See SNOMED Licensing or NCTS Australian affiliate licensing. |
| Logical Observation Identifiers Names & Codes (LOINC) | See LOINC License. |
In addition, some code systems used by the FHIR API are licensed by the Australian Digital Health Agency under a Creative Commons Attribution 4.0 International License (CC BY 4.0). Others licensed by HL7 International, HL7 Australia, and the Australian Digital Health Agency are licensed under a Creative Commons No Rights Reserved License (CC0).