Stream: implementers
Topic: Supporting multiple FHIR versions in a single endpoint
Anand Mohan Tumuluri (Feb 03 2021 at 11:39):
We are planning to support multiple FHIR versions in a single endpoint using the fhirVersion MIME type parameter as described in http://build.fhir.org/versioning.html, supporting R4 in addition to the existing STU3 version. We are planning to isolate the versions in distinct silos and any references between resources with different versions are not allowed. This is done so that searches with includes result in a Bundle corresponding to a single version. (Example: R4 Observation pointing to STU3 Patient and a search for /Observation?_include=Observation:subject:Patient will yield a bundle with mixed versions)
However, what to do if the client supports both versions with a preference for one? For example:
GET /Observation?criteria with Accept: application/fhir+json;fhirVersion=4.0, application/fhir+json;fhirVersion=3.0;q=0.5
Is this even allowed? How is the server to identify which version silo to query?
Michele Mottini (Feb 03 2021 at 13:56):
I think you can safely assume that client would expect only one version. I would advise against using the fhirVersion mime type - just use separate end points, that's the standard way everyone uses currently
Cooper Thompson (Feb 03 2021 at 14:06):
The main issue with the multiple endpoint approach will come when IGs start being non-compatible. Then you'd need to have different endpoints for each non-compatible profile. I honestly expected more non-compatible IGs b y now, so maybe I'm wrong that day won't come and this won't end up being an issue.
René Spronk (Feb 03 2021 at 14:15):
Single end points are obviously very attractive if they have a capability to transform resources (or whatever format one uses as a persistence layer) to all versions supported.
Michele Mottini (Feb 03 2021 at 14:37):
Single end points are obviously very attractive if they have a capability to transform resources
Don't see that..?
Gino Canessa (Feb 03 2021 at 16:16):
The largest problem I ran into (having done a test server that way) is that clients generally do not include that parameter. If we could go back in time and make it the recommended (or even required) practice to include it, a single endpoint would work well. Without that, the applications that use your 'default' version (e.g., if you accept a non-versioned MIME type) will work and other users will ask for an endpoint with the other default.
Lloyd McKenzie (Feb 03 2021 at 17:22):
If multiple options are listed in the Accept header, they're listed in order of preference. The algorithm is the server goes through the list and returns the first that it supports.
Lloyd McKenzie (Feb 03 2021 at 17:22):
(That's HTTP rules, not anything FHIR-specific)
Anand Mohan Tumuluri (Feb 03 2021 at 19:24):
Thanks everyone. @Lloyd McKenzie 's answer makes sense and I am going to stick with that. Agree that single endpoint is indeed attractive & that this doesn't even matter if we could support dynamic transform between versions but that is a whole other big topic that I don't want to shoot myself with at the moment.
Gino Canessa (Feb 03 2021 at 19:26):
Yes Lloyd, but my point is that clients typically don't include the version parameter on the MIME type. In my experience, most clients (regardless of which version they implement) simply send application/fhir+json. Asking a majority of clients to change their software doesn't lend itself to wide/easy adoption.
Michele Mottini (Feb 03 2021 at 20:08):
most clients simply send application/fhir+json
...and the other ones send application/json or * or nothing . . . .
Lloyd McKenzie (Feb 03 2021 at 20:31):
If servers don't include the version, then you can't use content negotiation to handle multiple versions on the same endpoint.
Gino Canessa (Feb 03 2021 at 20:59):
Lloyd McKenzie said:
If servers don't include the version, then you can't use content negotiation to handle multiple versions on the same endpoint.
Exactly. While the specs indicate how this should work, in practice (since most clients don't provide the info), providing multiple versions in a single endpoint doesn't work well.
Just wanted to be clear on expectations... If someone is developing both sides, this works great. If you're developing a server, most clients won't support it. And, if you're developing a client; :shrug: (I assume most servers won't balk at it, but most servers I know of only support one version at an endpoint anyway).
Shamil Nizamov (Feb 03 2021 at 21:07):
I'm just wondering how one would define the CapabilityStatement.fhirVersion (code, 1..1) to support two FHIR versions.
Michele Mottini (Feb 03 2021 at 21:11):
You cannot - DSTU2 does not even have a CapabilityStatement
Paul Church (Feb 03 2021 at 21:12):
I guess you could give a different response to /metadata depending on the fhirVersion in the request, then at least the client could probe for all the different versions at that endpoint.
Lloyd McKenzie (Feb 03 2021 at 21:14):
If a single endpoint supports multiple versions, HTTP content negotiation determines what you get back. Thus far, we don't have a use-case for knowing all versions a server supports. What matters is "do you support any of the versions I do?" and "What's the most preferred version you support of those I support".
Lloyd McKenzie (Feb 03 2021 at 21:15):
If you're using CapabilityStatement from an IG perspective, you'd have a different statement for each version
Shamil Nizamov (Feb 03 2021 at 21:16):
It sounds as [base]/stu3/... or [base]/r4/... is much easier to implement.
Grahame Grieve (Feb 03 2021 at 21:22):
we don't have a use-case for knowing all versions a server supports
yes we do. See http://hl7.org/fhir/capabilitystatement-operation-versions.html
Grahame Grieve (Feb 03 2021 at 21:22):
It sounds as [base]/stu3/... or [base]/r4/... is much easier to implement.
yes, in the short term. But it has other consequences that will become more evident over time
Lloyd McKenzie (Feb 03 2021 at 22:34):
Sorry, I'd looked on the versions page but missed the operation-versions link.
Lloyd McKenzie (Feb 03 2021 at 22:35):
Once we get into R5, R6, R7 where the resources you support are essentially identical across all of those releases, it's going to suck to have to stand up a new endpoint only to spit out the same content.
Anand Mohan Tumuluri (Feb 03 2021 at 22:57):
Followup question: Is fhirVersion parameter also relevant for _format? It makes sense for full MIME types application/[fhir+]xml and application/[fhir+]json but is _format=json;fhirVersion=4.0 valid?
Matt Varghese (Feb 05 2021 at 01:02):
Are we misrepresenting HTTP specs when we say using the content-type will not work though? To play the devil's advocate, from the HTTP standpoint, I don't see why using content-type is any different from a separate path. Even the questions about the metadata endpoint should be resolvable by the request content-type to the metadata endpoint (CapabilityStatement will respond for R4 and STU3, Conformance will respond for DSTU2)?
Matt Varghese (Feb 05 2021 at 01:10):
Lloyd McKenzie said:
Once we get into R5, R6, R7 where the resources you support are essentially identical across all of those releases, it's going to suck to have to stand up a new endpoint only to spit out the same content.
Sometime back, I had asked if we can have a resource level FHIR version, so the same endpoint can mix and match resources - and perhaps transform libraries can help the client (and/or the server) where the desired version isn't available..
Lloyd McKenzie (Feb 05 2021 at 03:09):
You can't mix versions because schemas, reference implementations and other things all depend on consistent versioning. Even when we get to the point where 'many' artifacts are locked down and remain compatible from release to release, that doesn't mean all of them will be - and there can still be addition of new elements that will cause at least some issues. So all Bundles and other collections will still have to be restricted to a single version.
Anand Mohan Tumuluri (Feb 05 2021 at 08:10):
Followup question: Is
fhirVersionparameter also relevant for _format? It makes sense for full MIME types application/[fhir+]xml and application/[fhir+]json but is_format=json;fhirVersion=4.0valid?
Should I add a task for clarifying use of fhirVersion in _format?
René Spronk (Feb 05 2021 at 08:33):
Currently it wasn't intended to do that, but you could create a Jira issue to propose a change.
Last updated: Apr 12 2022 at 19:14 UTC
