Introduction

The Founda Healthcare Gateway is a vertically integrated API gateway served asSaaS that connects applications with healthcare data providers.

  • Data Provider: The system, or systems of the healthcare practitioner.
  • Data Consumer: The system that uses Founda’s uniform API to integrate with data Providers.
  • Applications: The person or organisation who builds and maintains the consumer that integrates into the Uniform API.

Data Consumers integrate once with Founda and then provide their services across different healthcare providers. Users of the Healthcare Gateway use one stable API to connect to various healthcare providers’ systems.

The gateway securely exposes multiple standardized information interfaces.FHIR is one of those interfaces. The gateway can process and translate between information and communication standards such asHL7v2,HL7 FHIR,CDA,EDIFACT as well as custom protocols.

The Healthcare Gateway is a standard-first platform and vendor agnostic. We solve integrations, so Applications can focus on delivering and optimizing patient care.

The Healthcare Gateway connects the entire healthcare industry, including: GPs, Hospitals, Laboratories, Patient apps, and more.

An application registers itself as a data Consumer within Founda and defines which healthcare resources and actions it requires.

Fine grained control

Healthcare providers on Founda can grant access to their resources which are exposed through the Founda platform. In case of a hospital this will be done by an IT manager, in case of a GP this will be enabled at their request by their system provider.

To integrate with the gateway, data Consumers fetch API resources and or configure webhooksto call their own services.

Data consumer

Adata Consumer is an actor of the Healthcare Gateway which fetches data from an other actor: thedata Provider. A consumer will be onboarded on the Founda Healthcare Gateway in order to setup and configure required information:

  • Configuration of thehook endpoint URL(s) in case the data Consumer wants to receive service initiation requests
  • Configuration of thehook endpoint's security type and security credentials

Authentication to data Consumer

The gateway, after the transaction is initiated, will forward the request to thedata Consumer by sending all available information to ahook endpoint.

The data Consumer can (optionally) activate methods of authentication supported by the Founda Healthcare Gateway:

  • Bearer Token
  • JWT
  • Oauth2(coming soon)

Bearer Token

A request to the data Consumer's hook is sent using aREST call that will include a specific header containing the authorization token

Authorization: Bearer <token>

The request payload is to be included in the body of the request.

If the data Consumer is able to verify the given token then it can consider the request valid and proceed.

More information about thespecifications

JWT

A request to the data Consumer's hook is sent usign a REST call that will include a specific header in the format ofJSON Web Token. The JWT will have to be verified by the data Consumer using apublic key.

The public key was exchanged with Founda during the onboarding process.

If the data Consumer is able to verify the given token then it can consider the request valid and proceed.

More information about thespecifications

Authentication to Founda

When fetching data from one of the endpoints present in the Healthcare Gateway the request will have to be authorized. Founda supports the following authentication machanisms:

  • Oauth2

Oauth2

During the onboarding process the data Consumer is provided with a Oauth2token andrefresh token. The token must be included in any request against the Health Gateway.

More information about thespecifications

API interaction

A data Consumer can perform actions on resources using the Unified API:pull

A data Provider can send instructions to a data Consumer to assist in service initiation or notifcation of subscribers:push

Pull

A consumer can request resources from the Unified API using the supported HTTP operations.

Push

A data Consumer can also receive service initiation requests from a data Provider. This includes the exchange of tokens. These tokens are only used for the initiation requests.

For any following requests, valid OAuth2 tokens need to be provided. See the sectionpull.

If a data Consumer is configured to receive requests from a data Provider the request will be forwarded to the data Consumer using an appropriate authentication mechanism.

Compliant logging of healthcare data

Different national standards require logging of parameters that are relevant to particular operations that may not be part of the request itself. For example, when requesting an observation of a patient via the uniform API it may be required to log the treatment relationship and name of the doctor on who is requesting the data. In order to be able to log this data in accordance with various national regulations theLOG-CDATA header andLOG-CDATA-FORMAT header are used.

LOG-CDATA Header

This header can contain a JSON object or sets of key:value pairs encoded according toattribute-value pairs inURIs. The content of these values is free to define except for reserved terms. All content will be logged. This field is optional.

Reserved keys

No key in the JSON object or in the key:value pairs may begin with_. Any value prepended with_ is reserved for future use.

LOG-CDATA-FORMAT Header

If this header is not present, the structure of theLOG-CDATA header is assumed to be key:value pairs. If theLOG-CDATA-FORMAT header is present it will be used to interpret the structure of theLOG-CDATA header.

  • If the value of theLOG-CDATA-FORMAT iskv the structure of theLOG-CDATA header will be interpreted as key:value pairs.
  • If the value of theLOG-CDATA-FORMAT isjson the structure of theLOG-CDATA header will be interpreted as a JSON object.

How to read the API documentation

The API documentation is actively being updated as new resources, extentions and profiles are supported. Currently the Unified API supports the documented resources according to theNICTIZ STU3 2017 profile. FHIR Core STU3 resources are implied when no Nictiz Profile is published. In some cases the documentation may not yet reflect the Nictiz profile, however the unified API does support it. Links to the resources are included for completeness.

Glossary of terms

TermMeaning
Application developerThe person or organisation who builds and maintains the consumer that integrates into the Uniform API.
Consumer systemThe system that uses Founda’s uniform API to integrate.
Founda FHIR APIThe FHIR resources exposed in the Uniform API.
Healthcare gatewayThe Founda platform that includes both the Uniform API and the Source System connectors.
Provider systemThe system, or systems of the healthcare practitioner.
UHRUniversal Healthcare Resource: a generic representation of an action on a healthcare information resource.
Uniform APIThe set of non-custom APIs Founda exposes to interact with healthcare providers’ data. The Founda FHIR API is a subset of these APIs.