Search receipts in FHIR
March 2, 2015 2 Comments
When writing a server that can respond to FHIR queries, it may not be clear what to do when you get a search parameter that you don’t understand. Or, for that matter, which of the defined search parameters against each resource you do need to support.
There’s a section in the spec that spells this out quite clearly. The short version is that apart from supporting a search on _id (effectively returning a resource based on its id), it’s up to the server to decide what it can support – and it should use the Conformance resource to make that clear to a prospective client.
And if the server receives a query parameter it doesn’t understand – then it simply ignores it! Now, that may sound a bit flaky, but the idea is that the server will process the query as best as it can – and will indicate in its response what parameters it used. In other words, it’s up to the client to check what parameters the server used when it receives the response.
In the case of a RESTful search, these parameters are encoded in the self link in the bundle that is turned, eg:
<link rel="self" href="http://example.org/Patient?name=peter"/>
And this is a SHALL – you have to do it. (Actually, the client is also supposed to check this – another SHALL ).
The server doesn’t otherwise indicate that the result set may not be in response the the parameters the client was expecting. Of course there’s nothing to stop the server including this information in an informative OperationOutcome resource in the bundle, which is probably the polite thing to do. (Remember that a server can put whatever resources it wants to in the response – the client can’t assume that they will all be of the type requested).
And the reason for the title of this post? Well, we’re adding FHIR functionality to a number of systems here at Orion Health, and I was explaining this to a colleague to whom English is a second language. It took a few minutes, and suddenly his face brightened and he said “Oh, you mean the server gives a receipt!”
Nice one, I thought…
(Oh and another little tip when writing a search routine? The client can use _count as a parameter to indicate how many results it would like to receive max before the server pages. Again optional, but a nice touch)
About David Hay
Note that there’s a reason why the server ignores parameters it doesn’t know – there’s all sorts of reasons to add parameters that aren’t related to search – RESTful stuff like _format, authentication related things, cache busting. It’s the way that HTTP works, so rather than insist that the server decide what it understands across it’s many layers, we rely on the echo if the client needs to check whether a particular parameter is supported
It will certainly benefit clients to check that the server will handle any search parameters likely to have a significant impact on the number of results returned. Reducing a query to something like all male patients might cause some performance issues! Specifying maximum result numbers is a nice feature – very LINQ-like.