Skip to main content

FHIR Clients

InterSystems products come with standard FHIR client classes that your standalone ObjectScript application or interoperability production can use to send an HL7® FHIR® request to a FHIR REST endpoint over HTTP or to a local InterSystems FHIR server. The methods that your application uses to make the requests are the same regardless of which FHIR client class your application is using. In each case, after instantiating the client class that corresponds to your use case, the application calls the method that corresponds to a FHIR interactionOpens in a new tab or operationOpens in a new tab.

You have three client classes to choose from:

Sends a FHIR request over HTTP to a FHIR endpoint. When instantiating the class, the URL of the FHIR server’s endpoint is identified by an entry in the Service Registry.

Sends a FHIR request to the Service of an InterSystems FHIR server in the same namespace. When instantiating the class, the InterSystems FHIR server is identified by the server’s endpoint (for example, /fhirapp/fhir/r4)

Uses an interoperability production to send a FHIR request over HTTP to a FHIR endpoint. It has two variations:

  • Send out a FHIR payload that has been formulated within a custom business host or retrieve FHIR data from within a business host.

  • Route a FHIR request from a standalone ObjectScript application through an interoperability production before being sent over HTTP.

For details about this interoperability FHIR client, see Interoperability FHIR Client.

These classes all inherit from a single base class, HS.FHIRServer.RestClient.BaseOpens in a new tab, that contains the logic for the methods that a FHIR client uses to perform a FHIR interaction or operation. Each type of FHIR client is instantiated with a CreateInstance() method.

Interactions and Operations

Within the RESTful architecture of the FHIR specification, a FHIR client works with resources on the server through interactions. A FHIR client developed with InterSystems technology provides methods that correspond to these interactions, allowing your ObjectScript code to perform an interaction with a single method call.

While the FHIR client provides at least one method for every interaction, it provides a single method regardless of which operation you are performing on the FHIR server. For details on invoking this method to perform an operation, see Operation( )Opens in a new tab in the Class Reference.

Calling an Interaction Method

If your FHIR client is writing to the server with interactions like update, it must use the SetRequestFormat() method to specify the format of the payload being written to the server. Possible formats are JSON, XML, Form, XPatch, and JPatch. Similarly, your FHIR client can specify the preferred format of the resources returned by the FHIR server using the SetResponseFormat. Possible formats are JSON and XML.

Unless the request and response formats change for individual interactions, your application can set them once and have them applied to all interaction methods. For example, a standalone FHIR client sending requests to a FHIR server over HTTP might set the request and response formats immediately after instantiating the client.

 Set clientObj = ##class(HS.FHIRServer.RestClient.HTTP).CreateInstance("MyFHIR.HTTP.Service")
 Do clientObj.SetRequestFormat("JSON")
 Do clientObj.SetResponseFormat("JSON")

Once the FHIR client class has been instantiated and the request and response formats set, the application can call methods that correspond to the FHIR interactions they want to perform on the server. To explore the FHIR interaction methods, including signatures, that are available to a FHIR client, refer to HS.FHIRServer.RestClient.BaseOpens in a new tab in the Class Reference. Note that FHIR interactions that allow conditional actions have two different methods. For example, your application can call Update() or ConditionalUpdate() depending on whether the update interaction is conditional.

The data type of the payload that is passed as an argument is determined by the type of FHIR client that has been instantiated.

  • For clients accessing a FHIR server over HTTP, the payload argument can be a string or stream.

  • For clients accessing an InterSystems FHIR server in the local namespace, the payload argument can be a string, stream, or dynamic object.

The following is an example of instantiating a FHIR client and performing a read interaction on the external FHIR server:

 Set clientObj = ##class(HS.FHIRServer.RestClient.HTTP).CreateInstance("MyFHIR.HTTP.Service")
 Do clientObj.SetResponseFormat("JSON")
 Set clientResponseObj = clientObj.Read("GET", "Patient", "123")

Including Custom Headers

If your FHIR request requires custom header information, for example to pass in an API key, use the SetOtherRequestHeaders()Opens in a new tab method. This method takes as an input a multidimensional array by reference, where each custom header has a subscript in the array. To populate an array with a custom header, provide a header name and a header value:

 Set otherHeaders("X-API-Key") = "123"
 Do clientObj.SetOtherRequestHeaders(.otherHeaders)

To clear the “other headers” collection for the Rest clientObj instance, use the ClearOtherRequestHeaders()Opens in a new tab API method. This method takes no arguments:

  Do clientObj.ClearOtherRequestHeaders()

Customizing Requests and Responses

Internally, each interaction method calls three overridable methods that can be customized to modify how a request is sent or to manipulate the response received by the request. These three methods, MakeRequest(), InvokeRequest(), and MakeClientResponseFromResponse() are implemented by each type of FHIR client, not in the base class. Refer to the comments in the FHIR client class for more information (HS.FHIRServer.RestClient.HTTPOpens in a new tab, HS.FHIRServer.RestClient.FHIRServiceOpens in a new tab, or HS.FHIRServer.RestClient.InteropOpens in a new tab).

Requests without FHIR Client Class

Though using a FHIR client class is recommended when making requests to an internal FHIR server from an ObjectScript application, it is possible to write custom classes that perform CRUD operations on the server without these standard client methods. For example, you can write a custom class to interact with the FHIR server without going through the Service, thereby bypassing restrictions on the interactions that are allowed. You can also make direct calls to the Service with the DispatchRequest() method. For more information about these special cases, see ObjectScript Applications.

FeedbackOpens in a new tab