Getting more than one type of Resource back in a FHIR query

I received an interesting question from a colleague at Orion Health today:

We’re looking at the Appointment API for FHIR for some upcoming work (http://fhir.azurewebsites.net/appointment.html).

The location (http://fhir.azurewebsites.net/location.html) of the appointment is a reference link in the API example, and we want to show that information in the list of appointments for the patient. With the current modelling I think that means we’d have one REST API call for the list and then a REST API for each appointment to get the location information. Do you know if there is any provision in FHIR for being able to “inline” the reference information for lists of content to reduce the number of HTTP requests necessary to obtain and present the information?

This is an interesting question, and one that has a number of solutions.

First – what is not: Contained resources. This was actually the subject of my very first post and you can read the details there, but briefly, contained resources are intended for situations where it is not possible to properly identify a resource – which is clearly not the situation here.

We’ll have a look at 4 possibilities (and there may be more):

• The display property
• The _include query parameter
• A compartment
• A custom service

The display property is the simplest solution. It is intended to identify what is being referenced (in this case a location resource) and is not a copy of the resource contents. The idea is that it should be enough to display in a list or some other display to the user – so would seem a good fit here. The downside is that it is populated by the resource creator, and may not have all the information that the consumer wants to display.

Next up is the _include query parameter. This allows the consumer to request that the server include other resources in the query, based on a query parameter. So the following query would ask that the server include in the response bundle the Location resources that are referenced by the Appointment resources that match the query

GET /Appointment?participant.individual={patientID}&_include=Appointment.location

The third possibility is the patient compartment. This is really a form of ‘syntactic sugar’ that allows queries to be more naturally expressed. So:

GET /Patient/{patientID}/Appointment?_include=Appointment.location

(btw – I’m not completely sure that this will work as the patient is not a single property. I’ll update the post if there are changes)

And finally, it would be possible to create a custom service – though with the options above, this doesn’t seem necessary, and these are really more intended where there is some business or task based logic to perform.

Note that only the first option is a core part of the FHIR spec – the other options depend on the server implementing them.

So there you go!

And if you are interested in the Appointment resource, now would be a good time to go and comment!