FHIR Requests and Responses

This topic discusses the requests and responses used by FHIR servers and the FHIR Adapter for Interoperability Productions.

For information about the requests and responses used by the InterSystems FHIR client, see FHIR Clients.

Non-production Requests/Responses

For a FHIR server that does not use an interoperability production:

The message class that the server architecture uses to pass HL7® FHIR® requests is HS.FHIRServer.API.Data.RequestOpens in a new tab.
The message class that the server architecture uses to pass responses from the server to the FHIR client where the request originated is HS.FHIRServer.API.Data.ResponseOpens in a new tab.

Accessing FHIR Payloads

By default, when a FHIR request is received by the REST handler, it stores the FHIR payload in the Json property of a Request object (HS.FHIRServer.API.Data.RequestOpens in a new tab), which automatically puts the JSON structure into a dynamic object. FHIR requests that contain XML are converted to JSON before being represented as a dynamic object in the Json property. Responses from the FHIR server (HS.FHIRServer.API.Data.ResponseOpens in a new tab) also contain a Json property for FHIR data.

Working with FHIR data begins by getting access to the Json property of the request or response. Once you have the FHIR payload, you can manipulate it as a dynamic object. For examples, see FHIR Data.

Interoperability Requests/Responses

For a FHIR server, FHIR Adapter for Interoperability Productions, or FHIR client that leverages an interoperability production:

The message class used to pass FHIR requests through the production is HS.FHIRServer.Interop.RequestOpens in a new tab.

The message class used to pass a response through the production HS.FHIRServer.Interop.ResponseOpens in a new tab.

Note:

If you construct a HS.FHIRServer.Interop.ResponseOpens in a new tab object, you must explicitly set the ContentType property in order to create the HTTP response Content-Type header. Setting the ResponseFormatCode in the HS.FHIRServer.API.Data.ResponseOpens in a new tab is not sufficient.

These classes include a property QuickStreamId that points to the FHIR payload.

Accessing FHIR Payloads

When a FHIR implementation is using an interoperability production, you access the FHIR payload of the message object differently than implementations where a production is not used. In production-based implementations, the request and response messages (HS.FHIRServer.Interop.RequestOpens in a new tab and HS.FHIRServer.Interop.ResponseOpens in a new tab) contain a QuickStreamId that is used to access a QuickStream object containing the FHIR payload. Though an interoperability request message also contains a Request property of type HS.FHIRServer.API.Data.RequestOpens in a new tab, this Request property cannot be used to access the FHIR payload because its Json property is transient (the same is true for interoperability responses). As a result, a business host in the production that needs to access the FHIR payload must use the QuickStreamID to obtain the payload.

If the payload is in JSON format, the business host can access the payload and convert it to a dynamic object in order to modify it. For example, a BPL business process could use the following code to access and modify the FHIR payload of a request message that is in JSON format:

 //Identify payload as a Patient resource and convert to dynamic object
 if ((request.Request.RequestMethod="POST") & (request.Request.RequestPath="Patient"))
 {
   set stream = ##class(HS.SDA3.QuickStream).%OpenId(request.QuickStreamId)
   set myPatient = ##class(%DynamicObject).%FromJSON(stream)

   // Modify Patient resource
   do myPatient.%Set("active", 0, "boolean")

   //Update payload with modified Patient resource
   do myPatient.%ToJSON(stream)
   do stream.%Save()
 }

For more examples of manipulating FHIR data as dynamic objects, see FHIR Data.

ObjectScript Applications

If an ObjectScript application needs to retrieve resources from the Resource Repository, it can build a non-production request object (HS.FHIRServer.API.Data.RequestOpens in a new tab) before dispatching it to the endpoint’s Service. If the application is retrieving data, it is returned as the non-production response object (HS.FHIRServer.API.Data.ResponseOpens in a new tab). For more details, see Direct Calls to DispatchRequest.

Setting the Client-Visible URL

In some cases—notably, when requests are forwarded to a FHIR endpoint through a proxy—the URL at which the FHIR server received a request may differ from the URL which was originally requested by a REST client.

In such cases, the FHIR Server’s rest handler determines the client-visible base URL from the content of a request object’s FORWARDED or X-FORWARDED HTTP headers. This logic is implemented by the GetBaseURL()Opens in a new tab class method of the HS.FHIRServer.Util.BaseURLOpens in a new tab class.

If your FHIR server must construct the client-visible URL according to a different logic, simply define a custom GetBaseURL() in the HS.Local.FHIRServer.Util.BaseURLOpens in a new tab class. A method defined in this class will override the original.

Working with FHIR Data

FHIR Clients