Skip to content

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 result

FHIR version

The FHIR API is currently based on:

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 maximum result size of queries is 8MB.
  • 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.

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).

Prev: Halo Cloud overview Next: FHIR API Capabilities

Version: 24.1112.3950