Skip to main content
Previous sectionNext section

FHIR Clients

InterSystems products come with standard FHIR® client classes that your standalone ObjectScript application or interoperability production can use to send a 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 interaction or operation.

You have three client classes to choose from:

FHIR Client Description
HS.FHIRServer.RestClient.HTTP 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.
HS.FHIRServer.RestClient.FHIRService 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)
HS.FHIRServer.RestClient.Interop 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.Base, 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 the Operation( ) 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")
Copy code to clipboard

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 the HS.FHIRServer.RestClient.Base 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")
Copy code to clipboard

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.HTTP, HS.FHIRServer.RestClient.FHIRService, or HS.FHIRServer.RestClient.Interop).

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.

Feedback