Halo Cloud overview

Halo Cloud is a collection of API products and meta-level APIs that enable easier integration with practice management systems (PMSs) via the cloud.

All Halo Cloud APIs are RESTful APIs accessible through HTTPs that return JSON-encoded responses and use standard HTTP response codes.

Our long-term goal is to offer a range of API products for a variety of use cases, bridging the gap between various practice management systems. Our currently available API products are:

SQL Passthrough API

An unopinionated SQL passthrough API which allows integrators to run standard SQL queries on practice databases via Halo Cloud APIs.
- Maximum flexibility by allowing direct SQL access.
- Minimal work required to switch existing SQL-based integrations to Halo Cloud.
- Reduces development costs of new integrations by removing the need to develop and install a local agent on practice servers.
Read more
FHIR API

The FHIR API is an upcoming API product which will give integrators a new way to interact with PMS systems, no SQL required, using the HL7® FHIR® standard.
- Maximum interoperability with other health care systems.
- Develop for the future by adopting the standards Australian health care is moving towards.
- Reduces the work required to understand the specifics of the PMS database by surfacing the data using an international standard.
Read more

Definitions

Many of the following terms are explained in more detail elsewhere in these docs. The following is just a quick reference guide.

Term	Definition	More info
Practice server(s)	A server or set of servers which support one or more practices, on which the PMS database and Halo Link are installed.
Halo GUID	Halo Connect's unique identifier for each practice server with Halo Link installed.	Link
Halo Link	Halo Connect's local agent which enables communication with on-premise PMS databases.	Link
Halo Cloud	Halo Connect's collection of API products and meta-level API endpoints.
Authoritative Halo Link instance	The singular Halo Link instance integrations are allowed to connect to.	Link
Non-authoritative Halo Link instance(s)	Any other Halo Link instances that integrations are not allowed to connect to.	Link

Overview of functionality

Supported PMSs

Halo Cloud currently works with the following PMS software:

Limitations

Halo Cloud currently does not:

Interact with front-end PMS software such as the UI clients practice staff use. Halo Cloud only interacts with PMS databases.
Allow integrators to access data at practices they have not been enabled for, or for PMS providers they have not signed up with. Halo Cloud builds on top of existing PMS authorisation and authentication systmes.
Enable queries to be fanned out over multiple practices. Queries can only be sent to one practice at a time.

Quotas and rate limits

In order to protect practice servers and integrators from performance issues due to spikes in query rates, we apply a rate limit to queries in both staging and production. Over a rolling 5 second period, integrators can send at most 15 queries total of the following types:

SQL Passthrough immediate query POSTs
FHIR API POSTs
FHIR API GETs

The rate limit does not apply to SQL Passthrough asynchronous queries.

Authentication and authorisation

Halo Cloud leverages the existing authentication and authorisation systems of the PMSs it integrates with, and adds additional systems on top. This means:

Integrators must onboard with the PMS provider as usual and receive the required access and credentials to be able to run queries on PMS databases via Halo Cloud.
Practices enable and disable integrations as usual, and disabled integrations can not communicate with the practice database via Halo Cloud.

Halo Cloud authentication

When you sign up for Halo Cloud you will receive a subscription key which allows you to send queries via Halo Cloud -- though only to practices which have enabled your integration in the PMS software.

See Getting started with Halo Cloud for how to authenticate with Halo Cloud.

PMS database authorisation

Halo Connect does not handle PMS database access authorisation. What data integrators can access is managed by the respective PMS vendor. For this reason, using Halo Cloud requires integrators to have onboarded with the relevant PMS vendor before they can query any practices using that PMS via Halo Cloud.

When an integrator onboards with Halo Connect, we coordinate with the relevant PMS vendor(s) to securely store the integrator's credentials. When the integrator sends us a query, we then use those credentials to run the query on the specified practice server on their behalf.

If you find that your database access is not sufficient for your product, please reach out to the relevant PMS to discuss expanding your access.

Security and monitoring

Halo Connect does monitor the health of queries and Halo Link instances connected to our network using metadata. This allows us to proactively work to resolve any service disruptions, and to help practices and integrators with any issues they might encounter.

Halo Connect does not inspect, monitor, or log any data in or retrieved from practice databases, nor do we store any such data, except for practice metadata like practice name and PMS ID. This is used to identify practices for query routing.

Please see our Security overview for more information, particularly regarding our Shared Responsibility Model.

API structure

Halo Cloud contains two main APIs:

Integrator API contains both admin and query endpoints, and is designed to be used by integrator's cloud services. This is the main API, and works for all supported PMSs.
Device API contains a subset of endpoints and stronger auth mechanisms, and is designed to be used by on-premise applications. Supported by Zedmed and D4W.

The APIs have separate API references, available via the navigation menu on the left.

Within these APIs, there are multiple products and query groups:

Site APIs for practice onboarding and metadata.
Token API handles authentication for the Device API. Please note, the Token API is documented in the Device API reference but is technically part of the Integrator API, based on its request URL and requirement for being called from an integrator's cloud, not on-premise applications.
SQL Passthrough API contains endpoints for querying practices via SQL.
FHIR API contains endpoints for querying practices via FHIR requests.

Finally, within the SQL Passthrough API are three types of queries:

Immediate queries are for small, fast queries that are given priority in the queue. This type is recommended for real-time use cases.
Registered queries are repeating queries that run at a specified frequency, and can be used to monitor for updates or new records. This type is recommended for polling use cases.
Async queries are for any other queries, but are particularly useful for large queries due to their pagination and no size limit.

Webhook notifications are supported for both Registered and Async queries.

The API references will also list Registered queries as their own section. This is for ease of reading and because support for Registered Queries may also be added to the FHIR API in the future.

Integrator vs Device API

To clarify why both the Integrator and Device APIs exist:

Integrator API
- Designed for machine-to-machine communication, secured by modern cloud technologies.
- Leans on cloud security to allow for a simpler auth and query workflow.
- Includes admin and meta endpoints for retrieving practice metadata and Device API tokens.
- Allows queries across all practices an integrator is allowed to access.
- Supported by all PMSs.
Device API
- Designed for communication between Halo Cloud and insecure, on-premise devices.
- Ensures API keys are not stored on local devices by requiring a more complex auth workflow.
- Does not include admin and meta endpoints. Only includes query endpoints.
- Restricts queries to a specific device at a specific practice.
- Supported by Zedmed and D4W.

Using Halo Cloud

See Getting started with Halo Cloud for requirements and setup steps.

Next: Getting started with Halo Cloud