The first time I tried to page through results in FHIR I got it wrong.
I built a screen with Next and Previous links — all based on incorrect assumptions about Bundle link URLs.
My app worked for a single FHIR server. It failed on all other servers.
Here’s an example of a Bundle returned by the Firely test server for a Patient GET request.
A bundle total exists and the “self” link uses _count and _skip parameters that suggest an easy approach to pagination.
Surely I can build my app’s pagination around this? I could include breadcrumbs and deep links to other pages. I could have a “last” page link calculated from the total count and the _skip parameter.
Unfortunately not.
While my app might work for this one server today, it won’t work with other FHIR servers.
There are a number of reasons for this.
– Link URL parameters are not part of the FHIR spec
One server might use _offset, another might use _skip, another might rely on random values or GUIDs. And these can change at any time.
– You can’t assume a Bundle total will be returned
Chances are it will be, but it’s not mandatory. There are FHIR servers that do not return a total. And there are FHIR servers that return an estimated total.
– You can’t rely on the _count value
First, you may not know the maximum _count in advance for a particular server. Second, it’s not required to be a link URL parameter. And finally, the count of resources returned can change when included resources are part of the response.
The message here is that in order to successfully paginate results in FHIR you MUST use the provided Bundle links as they are: “self”, “prev” and “next”.
You cannot and should not construct your own URLs based on parameters you find for individual FHIR servers.
There was a lively discussion on this topic a couple of weeks ago on the FHIR chat forum.
https://chat.fhir.org/#narrow/stream/179166-implementers/topic/_count.20and.20CapabilityStatements
Well worth a read!
And if anyone is interested in the app I was building that got this wrong, it was Vanya. My pagination worked perfectly for Azure FHIR servers, but failed on Firely and HAPI servers.
---