Client

fhir-kit-client~ Client

new Client(config)

Create a FHIR client.

For details on what requestOptions are available, see the node request documentation at https://github.com/request/request

Source:
Parameters:
Name Type Description
config Object

Client configuration

Name Type Attributes Description
baseUrl String

ISS for FHIR server
customHeaders Object <optional>

Optional custom headers to send with each request
requestOptions Object <optional>

Optional custom request options for
requestSigner function <optional>

Optional pass in a function to sign the request. instantiating the HTTP connection
bearerToken String <optional>

Optional bearerToken to use for each request.
Throws:

An error will be thrown unless baseUrl is a non-empty string.

Example
// minimial example
const client = new FhirKitClient({ url: 'http://baseurl/fhir' });

// exhaustive example
const options = {
  baseUrl: 'http://baseurl/fhir',
  customHeaders: {
    'x-some-header': 'some-custom-value'
  },
  requestOptions: {
    cert: certFileContent,
    key: keyFileContent,
    ca: caFileContent
  },
  bearerToken: 'eyJhbGci...dQssw5c',
  requestSigner: (url, requestOptions) => {
     const signed = aws4.sign({
       path: url,
       service: 'healthlake',
       region: 'us-west-2',
       method: requestOptions.method
     });
     Object.keys(signed.headers).forEach((key) => {
       requestOptions.headers.set(key, signed[key]);
     });
   }
};

const client = new Client(options);

Members

baseUrl

Get the baseUrl.

Source:

baseUrl

Set the baseUrl.

Source:

bearerToken

Set the Authorization header to "Bearer ${token}".

Source:

customHeaders

Get custom headers.

Source:

customHeaders

Set custom headers.

Source:

Methods

(static) httpFor(requestResponse) → {Object}

Given a Client response, returns the underlying HTTP request and response objects.

Source:
Parameters:
Name Type Description
requestResponse Object

to one of the FHIR Kit Client requests
Returns:
Type:
Object

object containing http request and response

Example
const Client = require('fhir-kit-client');

fhirClient.read({
  resourceType: 'Patient',
  id: 12345,
}).then((data) => {
  const { response, request } = Client.httpFor(data);
  console.log(response.status);
  console.log(request.headers);
});

batch(params) → {Promise.<Object>}

Submit a set of actions to perform independently as a batch.

Update, create or delete a set of resources in a single interaction. There should be no interdependencies between entries in the bundle.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
body string

The request body with a type of 'batch'.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resources in a FHIR Bundle structure.

Example
const requestBundle = {
  'resourceType': 'Bundle',
  'type': 'batch',
  'entry': [
   {
     'fullUrl': 'http://example.org/fhir/Patient/123',
     'resource': {
       'resourceType': 'Patient',
       'id': '123',
       'active': true
     },
     'request': {
       'method': 'PUT',
       'url': 'Patient/123'
     }
   },
    {
      'request': {
        'method': 'DELETE',
        'url': 'Patient/2e27c71e-30c8-4ceb-8c1c-5641e066c0a4'
      }
    },
    {
      'request': {
        'method': 'GET',
        'url': 'Patient?name=peter'
      }
    }
  ]
}

// Using promises
fhirClient.batch({
  body: requestBundle
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.batch({
  body: requestBundle
});
console.log(response);

(async) capabilityStatement(paramsopt) → {Promise.<Object>}

Get the capability statement.

Source:
Parameters:
Name Type Attributes Description
params Object <optional>

The request parameters.

Name Type Attributes Description
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

capability statement FHIR resource.

Example
// Using promises
fhirClient.capabilityStatement().then((data) => { console.log(data); });

// Using async
let response = await fhirClient.capabilityStatement();
console.log(response);

compartmentSearch(params) → {Promise.<Object>}

Search for FHIR resources within a compartment. The resourceType and id must be specified.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String

The resource type (e.g. "Patient", "Observation").
compartment Object

The search compartment.
searchParams Object <optional>

The search parameters, optional.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
postSearch Boolean <optional>

if true, all searchParams will be placed in the request body rather than the url, and the search will use POST rather than GET
Returns:
Type:
Promise.<Object>

FHIR resources in a Bundle

Example
// Using promises
fhirClient.compartmentSearch({
  resourceType: 'Observation',
  compartment: { resourceType: 'Patient', id: 123 },
  searchParams: { code: 'abc' }
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.compartmentSearch({
  resourceType: 'Observation',
  compartment: { resourceType: 'Patient', id: 123 },
  searchParams: { code: 'abc' }
});
console.log(response);

create(params) → {Promise.<Object>}

Create a resource.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String

The FHIR resource type.
body String

The new resource data to create.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resource

Example
const newPatient = {
  resourceType: 'Patient',
  active: true,
  name: [{ use: 'official', family: 'Coleman', given: ['Lisa', 'P.'] }],
  gender: 'female',
  birthDate: '1948-04-14',
}

// Using promises
fhirClient.create({
  resourceType: 'Patient',
  body: newPatient,
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.create({
  resourceType: 'Patient',
  body: newPatient,
})
console.log(response);

delete(params) → {Promise.<Object>}

Delete a resource by FHIR id.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String

The resource type (e.g. "Patient", "Observation").
id String

The FHIR id for the resource.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

Operation Outcome FHIR resource

Example
// Using promises
fhirClient.delete({
  resourceType: 'Patient',
  id: 12345,
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.delete({ resourceType: 'Patient', id: 12345 });
console.log(response);

history(params) → {Promise.<Object>}

Retrieve the change history for a FHIR resource id, a resource type or the entire system

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType string <optional>

The resource type (e.g. "Patient", "Observation"), optional.
id string <optional>

The FHIR id for the resource, optional.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resources in a FHIR Bundle structure.

Example
// Using promises
fhirClient.history({ resourceType: 'Patient', id: '12345' });
  .then((data) => { console.log(data); });

// Using async
let response = await fhirClient.history({ resourceType: 'Patient', id: '12345' });
console.log(response);

nextPage(params, headersopt) → {Promise.<Object>}

Return the next page of results.

Source:
Parameters:
Name Type Attributes Description
params Object

The request parameters. Passing the bundle as the first parameter is DEPRECATED

Name Type Attributes Description
bundle object

Bundle result of a FHIR search
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resources in a FHIR Bundle structure.

operation() → {Promise.<Object>}

Run a custom FHIR operation on system, resource type or instance level.

  • To run a system-level operation, omit the resourceType and id parameters.
  • To run a type-level operatiion, include the resourceType and omit the id parameter.
  • To run an instance-type operation, include both the resourceType and id.
Source:
Parameters:
Name Type Attributes Description
params.name String

The name of the operation (will get prepended with $ if missing.
params.resourceType String <optional>

Optional The resource type (e.g. "Patient", "Observation")
params.id String <optional>

Optional FHIR id for the resource
params.method String <optional>

Optional The HTTP method (post or get, defaults to post)
params.input Object <optional>

Optional input object for the operation
params.options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

Result of opeartion (e.g. FHIR Parameter)

Example
client.operation({ resourceType: 'ConceptMap', name: '$apply' }).
  then(result => console.log(result).
  catch(e => console.error(e));


const input = {
 system: 'http://hl7.org/fhir/composition-status',
 code: 'preliminary',
 source: 'http://hl7.org/fhir/ValueSet/composition-status',
 target: 'http://hl7.org/fhir/ValueSet/v3-ActStatus'
};

client.operation({resourceType: 'ConceptMap', name: 'translate', method: 'GET', input}).
  then(result => console.log(result)).
  catch(e => console.error(e));

patch(params) → {Promise.<Object>}

Patch a resource by FHIR id.

From http://hl7.org/fhir/STU3/http.html#patch: Content-Type is 'application/json-patch+json' Expects a JSON Patch document format, see http://jsonpatch.com/

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String

The resource type (e.g. "Patient", "Observation").
id String

The FHIR id for the resource.
JSONPatch Array

A JSON Patch document containing an array of patch operations, formatted according to http://jsonpatch.com/.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resource

Example
// JSON Patch document format from http://jsonpatch.com/
const JSONPatch = [{ op: 'replace', path: '/gender', value: 'male' }];

// Using promises
fhirClient.patch({
  resourceType: 'Patient',
  id: 12345,
  JSONPatch,
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.patch({
  resourceType: 'Patient',
  id: 12345,
  JSONPatch
});
console.log(response);

prevPage(params, headersopt) → {Promise.<Object>}

Return the previous page of results.

Source:
Parameters:
Name Type Attributes Description
params Object

The request parameters. Passing the bundle as the first parameter is DEPRECATED

Name Type Attributes Description
bundle object

Bundle result of a FHIR search
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resources in a FHIR Bundle structure.

read(params) → {Promise.<Object>}

Get a resource by FHIR id.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String

The resource type (e.g. "Patient", "Observation").
id String

The FHIR id for the resource.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resource

Example
// Using promises
fhirClient.read({
  resourceType: 'Patient',
  id: 12345,
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.read({ resourceType: 'Patient', id: 12345 });
console.log(response);

request(requestUrl, params) → {Promise.<Object>}

Run a request.

Source:
Parameters:
Name Type Description
requestUrl String

URL, can be relative to base or absolute
params Object

(optional) Request params

Name Type Description
method String

(optional) HTTP method (defaults to GET)
options Object

(optional) additional request options (e.g. headers)
body Object

(optional) request body
Returns:
Type:
Promise.<Object>

Response

Example
// Defaults to GET
fhirClient.request('Patient/123')
  .then(data => console.log(data));

fhirClient.request('Patient/123', { method: 'DELETE'})
  .then(data => console.log(data));

fhirClient.request('Patient', { method: 'POST', body: myNewPatient })
  .then(data => console.log(data));

(async) resolve(params) → {Promise.<Object>}

Resolve a reference and return FHIR resource

From: http://hl7.org/fhir/STU3/references.html, a reference can be: 1) absolute URL, 2) relative URL or 3) an internal fragement. In the case of (2), there are rules on resolving references that are in a FHIR bundle.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
reference String

FHIR reference
context Object <optional>

Optional bundle or FHIR resource
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resource

Example
// Always does a new http request
client.resolve({ reference: 'http://test.com/fhir/Patient/1' }).then((patient) => {
  console.log(patient);
});

// Always does a new http request, using the client.baseUrl
client.resolve({ reference: 'Patient/1' }).then((patient) => {
  console.log(patient);
});

// Try to resolve a patient in the bundle, otherwise build request
// at client.baseUrl
client.resolve({ reference: 'Patient/1', context: bundle }).then((patient) => {
  console.log(patient);
});

// Resolve a patient contained in someResource (see:
// http://hl7.org/fhir/STU3/references.html#contained)
client.resolve({ reference: '#patient-1', context: someResource }).then((patient) => {
  console.log(patient);
});

resourceHistory(params) → {Promise.<Object>}

Retrieve the change history for a particular resource FHIR id.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType string

The resource type (e.g. "Patient", "Observation").
id string

The FHIR id for the resource.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resources in a FHIR Bundle structure.

Example
// Using promises
fhirClient.resourceHistory({ resourceType: 'Patient', id: '12345' });
          .then((data) => { console.log(data); });

// Using async
let response = await fhirClient.resourceHistory({ resourceType: 'Patient', id: '12345' });
console.log(response);

resourceSearch(params) → {Promise.<Object>}

Search for a FHIR resource.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String

The resource type (e.g. "Patient", "Observation").
searchParams Object

The search parameters.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
postSearch Boolean <optional>

if true, all searchParams will be placed in the request body rather than the url, and the search will use POST rather than GET
Returns:
Type:
Promise.<Object>

FHIR resources in a Bundle

Example
// Using promises
fhirClient.resourceSearch({
  resourceType: 'Patient',
  searchParams: { name: 'Smith' },
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.resourceSearch({
  resourceType: 'Patient',
  searchParams: { name: 'Smith' },
});
console.log(response);

Search for a FHIR resource, with or without compartments, or the entire system

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String <optional>

The resource type (e.g. "Patient", "Observation"), optional.
compartment Object <optional>

The search compartment, optional.
searchParams Object <optional>

The search parameters, optional.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
postSearch Boolean <optional>

if true, all searchParams will be placed in the request body rather than the url, and the search will use POST rather than GET
Throws:

if neither searchParams nor resourceType are supplied

Type
Error
Returns:
Type:
Promise.<Object>

FHIR resources in a Bundle

Example
// Using promises
fhirClient.search({
  resourceType: 'Observation',
  compartment: { resourceType: 'Patient', id: 123 },
  searchParams: { code: 'abc', _include: ['Observation:encounter', 'Observation:performer'] },
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.search({
  resourceType: 'Observation',
  compartment: { resourceType: 'Patient', id: 123 },
  searchParams: { code: 'abc', _include: ['Observation:encounter', 'Observation:performer'] },
});
console.log(response);

(async) smartAuthMetadata(paramsopt) → {Promise.<Object>}

Obtain the SMART OAuth URLs from the Capability Statement, or any of the .well-known addresses.

See: http://docs.smarthealthit.org/authorization/conformance-statement/

Source:
Parameters:
Name Type Attributes Description
params Object <optional>

The request parameters.

Name Type Attributes Description
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

contains the following SMART URL: authorizeUrl, tokenUrl, registerUrl, manageUrl

Example
// Using promises
fhirClient.smartAuthMetadata().then((data) => { console.log(data); });

// Using async
let response = await fhirClient.smartAuthMetadata();
console.log(response);

systemHistory(paramsopt) → {Promise.<Object>}

Retrieve the change history for all resources.

Source:
Parameters:
Name Type Attributes Description
params Object <optional>

The request parameters.

Name Type Attributes Description
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resources in a FHIR Bundle structure.

Example
// Using promises
fhirClient.systemHistory();
          .then((data) => { console.log(data); });

// Using async
let response = await fhirClient.systemHistory();
console.log(response);

systemSearch(params) → {Promise.<Object>}

Search across all FHIR resource types in the system. Only the parameters defined for all resources can be used.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
searchParams Object

The search parameters.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
postSearch Boolean <optional>

if true, all searchParams will be placed in the request body rather than the url, and the search will use POST rather than GET
Returns:
Type:
Promise.<Object>

FHIR resources in a Bundle

Example
// Using promises
fhirClient.systemSearch({
  searchParams: { name: 'smith' }
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.systemSearch({ searchParams: { name: 'smith' } });
console.log(response);

transaction(params) → {Promise.<Object>}

Submit a set of actions to perform independently as a transaction.

Update, create or delete a set of resources in a single interaction. The entire set of changes should succeed or fail as a single entity. Multiple actions on multiple resources different types may be submitted. The outcome should not depend on the order of the resources loaded. Order of processing actions: DELETE, POST, PUT, and GET. The transaction fails if any resource overlap in DELETE, POST and PUT.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
body String

The request body with a type of 'transaction'.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resources in a FHIR Bundle structure.

Example
const requestBundle = {
  'resourceType': 'Bundle',
  'type': 'transaction',
  'entry': [
   {
     'fullUrl': 'http://example.org/fhir/Patient/123',
     'resource': {
       'resourceType': 'Patient',
       'id': '123',
       'active': true
     },
     'request': {
       'method': 'PUT',
       'url': 'Patient/123'
     }
   },
    {
      'request': {
        'method': 'DELETE',
        'url': 'Patient/2e27c71e-30c8-4ceb-8c1c-5641e066c0a4'
      }
    },
    {
      'request': {
        'method': 'GET',
        'url': 'Patient?name=peter'
      }
    }
  ]
}

// Using promises
fhirClient.transaction({
  body: requestBundle
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.transaction({
  body: requestBundle
});
console.log(response);

typeHistory(params) → {Promise.<Object>}

Retrieve the change history for a particular resource type.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType string

The resource type (e.g. "Patient", "Observation").
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resources in a FHIR Bundle structure.

Example
// Using promises
fhirClient.typeHistory({ resourceType: 'Patient' });
          .then((data) => { console.log(data); });

// Using async
let response = await fhirClient.typeHistory({ resourceType: 'Patient' });
console.log(response);

update(params) → {Promise.<Object>}

Update a resource by FHIR id.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String

The resource type (e.g. "Patient", "Observation").
id String

The FHIR id for the resource.
searchParams String

For a conditional update the searchParams are specified instead of the id, see https://www.hl7.org/fhir/http.html#cond-update
body String

The resource to be updated.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resource

Example
const updatedPatient = {
  resourceType: 'Patient',
  birthDate: '1948-04-14',
}

// Using promises
fhirClient.update({
  resourceType: 'Patient',
  id: 12345,
  body: updatedPatient,
}).then((data) => { console.log(data); });

// Using async
let response = await fhirClient.update({
  resourceType: 'Patient',
  id: 12345,
  body: updatedPatient,
});
console.log(response);

vread(params) → {Promise.<Object>}

Get a resource by id and version.

Source:
Parameters:
Name Type Description
params Object

The request parameters.

Name Type Attributes Description
resourceType String

The resource type (e.g. "Patient", "Observation").
id String

The FHIR id for the resource.
version String

The version id for the resource.
headers Object <optional>

DEPRECATED Optional custom headers to add to the request
options Object <optional>

Optional options object

Name Type Attributes Description
headers Object <optional>

Optional headers to add to the request
Returns:
Type:
Promise.<Object>

FHIR resource

Example
// Using promises
fhirClient.vread({
  resourceType: 'Patient',
  id: '12345',
  version: '1',
}).then(data => console.log(data));

// Using async
let response = await fhirClient.vread({
  resourceType: 'Patient',
  id: '12345',
  version: '1',
});
console.log(response);