One of the reasons we built Vanya was the difficulty we experienced using generic API tools such as Postman when querying FHIR APIs. That difficulty was nowhere more apparent than when we ran search queries using _include and _revinclude parameters and had to interpret the large Bundles that were returned by FHIR servers. Bundles of resources are essentially flat lists. They do not represent the hierarchical structure our queries suggested, making it difficult to connect resources together.

Vanya makes these connections for you in a hierarchical grid where included resources are connected up to a “parent” resource at all times. While the “parent” / “child” relationship is not accurate in terms of the data definitions, it is at least partially accurate when it comes to how that data is best viewed in response to a search query.

The Encounter resource is an ideal resource to illustrate how the _include and _revinclude parameters work and how that data can be represented. A typical Encounter connects to a lot of other resource types (_include), and a number of other resource types connect back to Encounter (_revinclude).

Queries using the _include parameter

The first sample query asks for all Encounters with a status of “finished”, sorted in reverse order so that the most recently updated appear first. It also asks for all Patient and Practitioner or RelatedPerson (Participant) resources referenced from the Encounter to be returned as well.


1. The search query _include parameters
Two _include parameters were added to the sample query, the first for Patient and the second for the participant. The participant could be a Practitioner, PractitionerRole or a RelatedPerson resource type. There is no limit to the number of _include parameters that can be added to a query, though different FHIR servers may have limits to the number of included resources returned.

2. Patient and Practitioner resources
In the results grid the first resource is an Encounter resource. Below the Encounter are two connected resources: a Patient and a Practitioner. If the same Practitioner or Patient were connected to other Encounters in the list, they would appear in the grid under each of those Encounters as well. This expanded hierarchical view means you can see every resource you asked for connected together.

3. Indicator that _include resources exist
The first column of each Encounter row will contain a small icon if any connected resources are available to view. Clicking on the icon “opens up” the connected resources. It’s very possible that not all Encounter resources in our query have a connected Practitioner or Patient, in which case no icon would appear in the first column.

4. Expanded details
Clicking on any row in the grid will populate the “Selected” and “JSON” sections to the right with complete details of every element in that resource. In the above example, we could click on an Encounter, Patient or Practitioner resource and see the complete details expanded.

Query using the _revinclude parameter

Reverse include queries tend to return a greater number of resources than queries that use the _include parameter. For this reason, many FHIR server providers limit the number of resources returned in response to _revinclude parameters. The sample query below illustrates both of these very well. In the query we’re asking for Encounters as before, but we’re also asking for all Observation resources that link back to these Encounters. Essentially, we’re asking for Observations made during an Encounter.


1. The _revinclude parameter
Specifies the resource and element that links back to the Encounter. The _count parameter is set to only 10 Encounter resources — any higher and we may have had a problem with the number of Observations returned in the response.

2. Observations returned
In the example above we’ve expanded the second Encounter returned. Straight away we can see that a lot of Observations were made during that Encounter — at least fifteen. There are a number of laboratory results as well as some vital signs.