Stream: argonaut
Topic: FHIR-27905: search by reference
Eric Haas (Oct 22 2020 at 16:38):
in J#27905 @Robert Scanlon asked to Clarify search by reference conformance expectations
What do implementers think is minimum needed?
e.g. : add bullet in Search Syntax to say...( paraphasing )
search by reference ... Patient/123 or just 123 or [base]/Patient/123
more formally stated as :
- note for values of type
reference(how to search by reference), the syntax {base}/{Type}/[id] means that the base url and Type values (where unambiguous*) are optional for the client to supply
"where unambiguous" means for a search parameter like patient the Type is assumed to be Patient. For a search parameter of subject it cannot be assumed.
Robert Scanlon (Oct 22 2020 at 20:51):
How do people feel about stating that formally in terms of server requirements? The server SHALL support search values of type reference of the form [base]/[Type]/[id] and [Type]/[id] in all cases. The server SHALL support search values of type reference of the form [id] where Type is unambiguous.
Robert Scanlon (Oct 22 2020 at 20:55):
I worry that people may interpret what 'optional for the client' means in terms of server requirements differently. Unless somewhere it is stated that 'optional for client' means 'required for server' at all times... though that seems like a dangerous statement.
Vassil Peytchev (Oct 22 2020 at 21:05):
The server SHALL support search values of type reference of the form [base]/[Type]/[id] and [Type]/[id] in all cases. The server SHALL support search values of type reference of the form [id] where Type is unambiguous.
Can you give examples of these (apparently) three different cases? I am not sure I follow...
Robert Scanlon (Oct 22 2020 at 21:14):
https://example.com/fhir/Procedure?patient=5https://example.com/fhir/Procedure?patient=Patient/5https://example.com/fhir/Procedure?patient=https://example.com/fhir/Patient/5
Vassil Peytchev (Oct 22 2020 at 22:24):
Thanks. Would the proposed rules apply to any and all references? Only the ones marked Must Support? Specific references only?
Eric Haas (Oct 22 2020 at 22:26):
only the searchparameters of type reference that are named in the guide: eg: AllergyIntolerance patient parameter
Cooper Thompson (Oct 26 2020 at 13:26):
Do Patient/5 and https://example.com/fhir/Patient/5 and mean different things? Or should the server treat them as if they were the same? I.e. if the resource on the server is using a relative URL in the reference, should it only find results if the relative reference is provided? Of should the server normalize the received search value and normalize the references in the resources and then do the search by comparing the normalized values?
I'm not sure I like having a server attempt to normalize the value received in the search parameter. Some references may be local to that logical FHIR server, but some might refer to an external FHIR server, so you'd then have to figure out when to normalize and when not to. But if you don't normalize, then if some resources have a full URL, and some just have the relative part, you'll probably only get a subset of what you expect.
Paul Church (Oct 26 2020 at 13:52):
We assume that the server knows its own base URL, and normalizes if and only if the URL matches that.
Cooper Thompson (Oct 26 2020 at 14:27):
Knowing your own base URL is tricky when you have reverse proxies, load-balanced VIPs, API managers etc. Especially if those are managed by a different entity than the one that manages the FHIR server. This has been a problem for us in other areas already.
Paul Church (Oct 26 2020 at 14:38):
Yes, that has been a complete nuisance for us as well. We've done full URL rewriting in a proxy layer, but that's a layer we control.
Cooper Thompson (Oct 26 2020 at 16:38):
Are you re-writing in your HTTP response bodies as well? I get re-writing stuff in the URL and HTTP headers, but trying to re-write everything in the actual body sounds terrible. And if/when we support signing FHIR resources, that would break signatures.
Paul Church (Oct 26 2020 at 16:45):
Yes. This isn't actually a production solution yet, but it rewrites URLs in the response body. In a typical deployment, the actual full URL of the GCP FHIR store is an internal implementation detail that the customer will not want to expose outside of the proxy and may not remain stable over time anyway.
Eric Haas (Oct 26 2020 at 17:23):
Cooper Thompson said:
Do Patient/5 and https://example.com/fhir/Patient/5 and mean different things? Or should the server treat them as if they were the same? I.e. if the resource on the server is using a relative URL in the reference, should it only find results if the relative reference is provided? Of should the server normalize the received search value and normalize the references in the resources and then do the search by comparing the normalized values?
I'm not sure I like having a server attempt to normalize the value received in the search parameter. Some references may be local to that logical FHIR server, but some might refer to an external FHIR server, so you'd then have to figure out when to normalize and when not to. But if you don't normalize, then if some resources have a full URL, and some just have the relative part, you'll probably only get a subset of what you expect.
I would like your opinion on this, This is to guide the client on allowed formats - so if the relative reference and absolute reference mean different things - The client needs to know this.
Paul Church (Oct 26 2020 at 19:45):
We also do the symmetric thing, a full URL reference in a resource will match a search for Patient/5 if the URL begins with the server's base URL. I would recommend that app clients always search for Patient/5, which puts the burden on the other side (whoever is writing the resources) to get it right.
Cooper Thompson (Oct 26 2020 at 21:00):
From our (Epic) perspective, right now we just support the raw ID (patient=5), and we always assume that the ID is relative to our logical server, and we don't address the subject issue. Our logical server can be known by many different URLs, but we need to know all the URLs we are known as to generate fullUrl for search bundles anyway, so it isn't a hard problem to accept an absolute URL reference and chop off the URL part.
I personally think it would be nice if we could get rid of absolute URLs in the REST API, and to my knowledge fullUrl in the search bundle is the big annoying one. However if we normalize reference searching to require the full URL format, then we're adding in another absolute URL requirement, and I'd rather we remove them.
I'm not bothered about Patient/5 vs. 5 for distinguishing the resource type of the subject you want, though it seems like a token-style syntax would be better there. It seems like Reference.type (ResourceType) is really the qualifier we want, but because of the REST API URL structure, that is I think entirely redundant with the path components of the reference.
Jenni Syed (Oct 27 2020 at 02:22):
Agree that a good base, and what I've seen in the wild, is the unqualified patient=X
Jenni Syed (Oct 27 2020 at 02:22):
I would definitely be interested in reasons why this might be hard on a client app
Jenni Syed (Oct 27 2020 at 02:23):
when FHIR supported the old subject param everywhere, we saw a lot of variation (and mistakes) in the way those parameters were used, but patient simplified this and removed a lot of the deviation we saw in applications.
Paul Church (Oct 27 2020 at 14:43):
I have no objection to patient=5. The only caveat is "Servers SHOULD reject a search where the logical id refers to more than one matching resource across different types" but that isn't likely to come up often.
Robert Scanlon (Oct 27 2020 at 14:45):
I would definitely be interested in reasons why this might be hard on a client app
From a generic client library perspective, reference_param=Type/id should always work when searching by any reference, while reference_param=id may or may not work depending on if that parameter applies to multiple types. So I can imagine some generic FHIR clients being explicit about the type always as a rule , and being surprised they have to understand that the parameter only applies to one type and therefore they can't prepend the type to the id always, automatically.
Robert Scanlon (Oct 27 2020 at 14:46):
I stress imagine because the client library I've worked on does not do this, and I would be surprised if the popular java, .net, and javascript libraries do this today (though I haven't looked deeply at them in some time).
Robert Scanlon (Oct 27 2020 at 14:47):
Also, the language in the search section is a little loose on if reference_param=Type/id is always expected to work or only will work in cases where the type is ambiguous, so that may be another count against this imagined scenario.
Paul Church (Oct 27 2020 at 14:49):
I think the explicit type should always be allowed and the language clarified if necessary. There's no value in disallowing it for unambiguous types.
Robert Scanlon (Oct 27 2020 at 14:55):
I would hope it is not much of a burden to accept both forms on unambiguous types to provide a little more leeway on the client side. But I recognize it is more stuff to maintain if there aren't any cases where there are ambiguous types (in US Core, today).
Last updated: Apr 12 2022 at 19:14 UTC
