Skip to content

Connect to a FHIR server

This page will showcase the different options to connect to the REST API of any FHIR server. In the simplest case (which is not recommended), you can connect to an unsecured REST API by intializing a server object with only base URL.

from fhir_kindling import FhirServer

fhir_server = FhirServer(api_address="http://fhir.example.com/R4")

Connecting with basic auth

To use basic auth, you need to provide the username and password.

from fhir_kindling import FhirServer

fhir_server = FhirServer(api_address="http://fhir.example.com/R4", username="my_username", password="my_password")

Connecting using a static token

Use a static token to connect to the FHIR server.

from fhir_kindling import FhirServer

fhir_server = FhirServer(api_address="http://fhir.example.com/R4", token="my_token")

Connect using OpenID Connect

To use OpenID Connect, you need to provide the client id and client secret, as well as the URL to the OpenID Connect server.

from fhir_kindling import FhirServer

fhir_server = FhirServer("https://fhir.server/fhir", client_id="client_id", client_secret="secret",
                         oidc_provider_url="url")

Initialization via environment variables

A connection to the server can be initialized based on environment variables. The keys for the environment variables corresponding to the above described authentication methods are the following:

  • Basic Auth:
    • FHIR_USER
    • FHIR_PW
  • Static Token:
    • FHIR_TOKEN
  • OIDC:
    • CLIENT_ID
    • CLIENT_SECRET
    • OIDC_PROVIDER_URL

Note

Make sure only one of the options is present in the environment. Otherwise, the connection will fail.

from fhir_kindling import FhirServer

fhir_server = FhirServer.from_env()

Advanced connection options

Headers & Proxies

Additional headers can be added to the request by setting the headers parameter when initializing the server object. The proxies parameter can be used to set proxies for the requests.

from fhir_kindling import FhirServer

fhir_server = FhirServer(api_address="http://fhir.example.com/R4", headers={"X-My-Header": "my_value"},
                         proxies={"http": "http://proxy.example.com:8080"})

Retrying request

By default all requests against a FHIR server that fail will raise an exception. This can be changed by setting either the retry_status_codes or retryable_methods when initializing the server object. The retry_status_codes is a list of status codes that should be retried. The retryable_methods is a list of HTTP methods that should be retried.

from fhir_kindling import FhirServer

fhir_server = FhirServer(api_address="http://fhir.example.com/R4", retry_status_codes=[500, 502, 503, 504])

Retry configuration

The default retry configuration is to retry 5 times with an exponential backoff. This can be changed by setting additional configuration parameters when initializing the server object. Read more about backoff and jitter here.

from fhir_kindling import FhirServer

fhir_server = FhirServer(
    api_address="http://fhir.example.com/R4",
    retry_status_codes=[500, 502, 503, 504],            
    retry_backoff_factor=0.5, 
    max_attempts=10, 
    max_backoff_wait=60
)