fhir_get_resources_by_ids: Get Resources by their IDs

Description

Downloads FHIR resources represented by a vector of resource IDs.

Usage

fhir_get_resources_by_ids(
  base_url,
  resource,
  ids,
  id_param = "_id",
  parameters = NULL,
  username = NULL,
  password = NULL,
  token = NULL,
  add_headers = NULL,
  verbose = 0
)

Value

A fhir_bundle_list containing the downloaded resources.

Arguments

base_url: A character vector of length one specifying the base URL of the FHIR server, e.g. "http://hapi.fhir.org/baseR4".
resource: A character vector of length one or fhir_resource_type object with the resource type to be searched, e.g. "Patient".
ids: A character vector containing the IDs of the resources that should be downloaded. In the default setting these should be resource (aka logical) IDs.
id_param: A character vector of length one containing the FHIR Search parameter belonging to the ids in ids. Defaults to "_id" meaning ids is interpreted as containing resource (aka logical) ids. Could be changed to "identifier" if ids contains a vector of identifier values instead.
parameters: FHIR Search parameters to further restrict the set of resources that is returned, e.g. gender=male to only download the resources from the ids list that correspond to males. Can be either a length 1 character containing properly formatted FHIR search parameters, e.g. "gender=male" or a named list or named character vector e.g. list(gender="male")or c(gender="male"). Defaults to NULL meaning no restriction on the IDs provided in ids.
username: A character vector of length one containing the username for basic authentication.
password: A character vector of length one containing the password for basic authentication.
token: A character vector of length one or object of class httr::Token, for bearer token authentication (e.g. OAuth2). See fhir_authenticate() for how to create this.
add_headers: A named character vector of custom headers to add to the HTTP request, e.g. c(myHeader = "somevalue") or c(firstHeader = "value1", secondHeader = "value2").
verbose: An integer vector of length 1 containing the level of verbosity. Defaults to 0.

Details

This function takes a character vector ids containing logical Ids of resources of a given type (specified in resource) on a FHIR server (specified in base_url) and downloads the corresponding resources from the server. The function will attempt to download the resources using a FHIR search request via POST where the IDs are part of the body. See fhir_search() for details. If this fails (e.g. because the server doesn't allow POST operations), the function falls back on a GET request. If the set of ids is too long to fit into one GET request (i.e. if the request gets longer than 2083 characters), it will be spread across several requests.

For more information on authentication options, please see the help page of fhir_search()

Examples

Run this code

# \donttest{

#the try({}, silent = TRUE) statement is only there to catch errors when the server is down
#you can skip it when the server is reachable

try({

#find IDs of Patient resources representing Homer Simpson
ids <- fhir_get_resource_ids(
  base_url   = 'https://hapi.fhir.org/baseR4',
  resource   = "Patient",
  parameters = "name=Homer&name=Simpson")

#Download all corresponding resources
bundles <- fhir_get_resources_by_ids(
  base_url = 'https://hapi.fhir.org/baseR4',
  resource = "Patient",
  ids      = ids)

#have a look at the resources
fhir_crack(
  bundles,
  fhir_table_description(
    resource = "Patient",
    cols     = list(
      ID      = "id",
      given   = "name/given",
      family  = "name/family")))

}, silent = TRUE)
# }