Configuration

The fhir_client has several configuration options available to developers.

You can use the client directly, or through the models. You can configure the client to use different versions of FHIR, and different FHIR formats. You can also configure a network proxy or using different security paradigms.

Creating a Client

client = FHIR::Client.new(url)

This client supports two modes of operation: basic and advanced. The basic mode is useful for simple operations because it promotes an ActiveRecord-like style of interaction. The advanced mode is less developer-friendly, but is currently necessary if you would like to use the entire range of operations exposed by FHIR.

Direct Usage

Model Usage

Associate the client with the model:

FHIR::Model.client = client

The FHIR models can now be used to directly interact with a FHIR server.

# read an existing patient with an ID of 'example'
patient = FHIR::Patient.read('example')

# update a patient
patient.gender = 'female'
patient.update # saves the patient

# create a patient
patient = FHIR::Patient.create(name: {given: 'John', family: 'Doe'})

#create a patient with specific headers
patient = FHIR::Patient.new(name: {given: 'John', family: 'Doe'}).create({Prefer: "return=representation"})

# search patients
results = FHIR::Patient.search(given: 'John', family: 'Doe')
results.count # results in an enumeration

# delete the recently created patient
patient.destroy

Configuring FHIR Version

The client defaults to R4 but can be switched to DSTU2 or STU3. It can also attempt to autodetect the FHIR version based on the metadata endpoint.

# autodetect the FHIR version
client = FHIR::Client.new(url)
version = client.detect_version
if version == :stu3
  puts 'FHIR Client using STU3'
elsif version == :dstu2
  puts 'FHIR Client using DSTU2'
elsif version == :r4
  puts 'FHIR Client using R4'
end

# tell the client to use R4
client.use_r4
# now use the client with the DSTU2 models
patient = FHIR::Patient.read('example')
patient = client.read(FHIR::Patient, 'example').resource

# tell the client to use STU3 (default)
client.use_stu3
# now use the client normally
patient = FHIR::STU3::Patient.read('example')
patient = client.read(FHIR::STU3::Patient, 'example').resource

# tell the client to use DSTU2
client.use_dstu2
# now use the client with the DSTU2 models
patient = FHIR::DSTU2::Patient.read('example')
patient = client.read(FHIR::DSTU2::Patient, 'example').resource

Configuring FHIR Format

The client defaults to json representation of resources but can be switched to xml representations.

client = FHIR::Client.new(url)

# Tell the client to use xml
client.default_xml

# Tell the client to use json
client.default_json

Configuring a Network Proxy

You can specify additional properties for the client including proxy information:

client.additional_headers = { Prefer: 'return=representation' }
client.proxy = 'https://your-proxy.com/'

Configuring Security

Security (in this case Authentication) is disabled by default. Authorization options are basic, OAuth2, and none.

No Auth

Authentication is disabled by default. It can be explicitly disabled by calling set_no_auth.

client.set_no_auth

Basic Auth

Basic HTTP Authentication is supported by the client.

client_id = 'Aladdin'
client_secret = 'open sesame'
client.set_basic_auth(client_id, client_secret)

OAuth2 Support

client = FHIR::Client.new(url)
client_id = 'example'
client_secret = 'secret'
options = client.get_oauth2_metadata_from_conformance
if options.empty?
  puts 'This server does not support the expected OAuth2 extensions.'
else
  client.set_oauth2_auth(client_id, client_secret, options[:authorize_url] ,options[:token_url], options[:site])
  reply = client.read_feed(FHIR::Patient)
  puts reply.body
end

Bearer Token Authorization

The fhir_client allows you to directly set a Bearer Token.

# token_response JSON:
# {
#  "access_token":"mF_9.B5f-4.1JqM",
#  "token_type":"Bearer",
#  "expires_in":3600,
#  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
# }
client.set_bearer_token(token_response['access_token'])