Stream: implementers
Topic: How do you let users know a newer API version is available?
lychenus (Nov 30 2020 at 05:51):
It seems there is no such prop in the object of observation
Ty
Grahame Grieve (Nov 30 2020 at 05:53):
if we did that, it would be in the CapabilityStatement. I recall some discussion about that, but not where we landed.
lychenus (Dec 03 2020 at 16:00):
lol its confusing too bad. lets say if you had a small mistake in the API we pull from the current database (which should be fairly common, and lets say such that the FHIR server does not act like a internet forum where people write and read, instead we transform some existing data into FHIR) and you want to correct that, not sure how to tell the users everywhere. and it seems there is not much available as i read in https://www.hl7.org/fhir/capabilitystatement.html
i do not know what people do on the other hand with the READ side, but if the JSON keep changing from time to time and there is no easy way to let users know, that could be annoying?
Michele Mottini (Dec 03 2020 at 16:08):
If the server generates valid FHIR the client should not notice the difference- they will see more or less data but they should be able to handle that
Eric Haas (Dec 03 2020 at 16:11):
I think you should consider Provenance
Cooper Thompson (Dec 03 2020 at 16:41):
API versioning is something we've struggled with. Fixing bugs or making changes without breaking backwards compatibility is hard. Most of the fixes or changes I'm talking about are valid FHIR both before and after, but you still get different content, and if apps were developed to expect one (valid FHIR) thing and we change it to another (valid FHIR) thing, stuff can break, and we have seen apps break in PRD. We don't have a great solution yet, but one option we've considered is an HTTP header that lets a client specify which API version they want (and if the header is omitted, they get the most recent version). A few years ago we talked about this, and whether there should be a standard versioning header, but I don't think it got any traction.
John Moehrke (Dec 03 2020 at 16:50):
everyone should be aware of the RISK they take on when they chose to deploy non-normative content. And everyone wanting to use something that is currently non-normative should do what ever they can to help move it to normative. This problem is mostly solved by the governance behind normative.
Cooper Thompson (Dec 03 2020 at 16:56):
The issues we have isn't about normative vs. non-normative. It could be fully normative and still have breaking changes in the content that is not related to the FHIR-compliance.
Cooper Thompson (Dec 03 2020 at 16:57):
There are two different "versions" at play: 1) the FHIR version (R4 vs. STU3) and 2) the API version.
John Moehrke (Dec 03 2020 at 16:58):
not true. HL7 governance around normative content is that it MUST NOT have breaking changes. So, yes it is a normative vs people choosing to use unstable specifications.
Cooper Thompson (Dec 03 2020 at 16:59):
We are talking (or I am, and I think the OP is) about breaking changes in the implementation of the API, not in the FHIR spec.
Cooper Thompson (Dec 03 2020 at 17:00):
For example, we had an issue with our implementation of DocRef where we were returning a date in DocRef.created when it should have been in DocRef.indexed. We deployed a fix, removing support for DocRef.created, and moving our date to DocRef.indexed. We had an app that was relying on DocRef.created, and didn't know to move over to looking at DocRef.indexed instead.
Cooper Thompson (Dec 03 2020 at 17:06):
This was DSTU2, but the same sort of issue could (and will, and has) exist in normative R4 resources.
Cooper Thompson (Dec 03 2020 at 17:11):
In fact, for R4 Patient (which is normative), we had a change where we added support for preferred names. Initially, the patient name was sent in Patient.name with use=usual. Then we broke out legal and preferred names, and started sending two names, the legal name with use=official and the preferred name with use=usual. Any system that was using patient name for matching, or that was expecting the name they get in use=usual to match some external name like from a wristband or paper form might need to update their app to now pull from the use=official name instead of use=usual. This was a breaking change in the implementation of the FHIR spec, not in the FHIR spec itself..
John Moehrke (Dec 03 2020 at 17:21):
I would call those things changes in the Profile. The profiles supported by the API are (can be) declared in the CapabilityStatement. Thus you could have indicated over time the change from one Profile (version) to another Profile (version).
Cooper Thompson (Dec 03 2020 at 17:25):
Does that mean that FHIR servers should be spawning dozens or hundreds of different sub-profiles? Like: "US Core Patient Epic Implemenation v1", "US Core Patient Epic Implemenation v2", "US Core Patient Epic Implemenation v3", etc.?
Cooper Thompson (Dec 03 2020 at 17:26):
Like ever time you deploy an implementation fix you need to spawn a new profile? That doesn't seem like a good solution to me.
Cooper Thompson (Dec 03 2020 at 17:28):
And all of those profiles would be specific to that particular vendor.
Cooper Thompson (Dec 03 2020 at 17:28):
Gross :(.
lychenus (Dec 03 2020 at 17:34):
people do make mistake and they fix.
mistakes aside, there are a lot of things that are different,
feet vs meters (imperial units vs SI units)
Asian BMI obesity boundary vs everyone else BMI obesity boundary
mmol/L and mg/dL unit changes in glucose level
lets say, there is an local legislation or a new global guideline that makes you change things in your API. how do you inform your users to update their own app? let alone some silly mistakes that gone unnoticed for years? and/or without eventually keeping a lot of API versions?
in my field sleep, there are different cults of people who use different parameters to track things, and those guidelines keep changing. (and they fight pretty often too)
this looked hypothetical, but i think it is very possible, and depending on how the FHIR service is structured.
Cooper Thompson (Dec 03 2020 at 17:37):
Yeah - I agree, there are a ton of different reasons an API implementation can change that has nothing to do with what is defined in the profile or the FHIR standard. None of those are changes from a standards perspective, but they are changes that a client app may care about.
Cooper Thompson (Dec 03 2020 at 17:38):
The question is whether that notification and versioning is something that should be solved in the FHIR standard, or if each implementation should come up with their own solution. A standard solution would be awesome, but addressing that sort of operational management is outside the scope of what HL7 normally handles.
Elliot Silver (Dec 03 2020 at 18:53):
Can't these sorts of things be handled with CapabilityStatement.software.version? (Well, at least for systems that receive the modified resources directly.)
Cooper Thompson (Dec 03 2020 at 20:00):
There issues with using CapabilityStatement is that most folks use version as a place for major release indicators (like v.1.2.1). The sort of change we'd need to track is more like git commit hash or something. And at least for us, those "commit hash" style versions are not necessarily sequential, so it would really need to be a full list of the installed patches. And it also doesn't enable using an old version (unless we publish dozens/hundreds of endpoint with different CapStatements).
Cooper Thompson (Dec 03 2020 at 20:01):
I'm interested in hearing from @lychenus , since I've sort of been projecting my problems on his question. Are we interpreting his issue/question correctly?
Grahame Grieve (Dec 03 2020 at 21:09):
I do think that you're talking about slightly different issues. You're talking about how to indicate that a new version of the API has been deployed, he's asking how to indicate that there's a new version somewhere else.
Grahame Grieve (Dec 03 2020 at 21:10):
generally, this is a poisoned chalice; you can insist that everyone checks the version, and then every deploy is a drawn out nightmare because you can't get everyone lined up. Else you tell Apps about it changes, and then they ignore it; at least you can blame the apps in this case.
Grahame Grieve (Dec 03 2020 at 21:11):
seems to me that the natural HTTP way to do this would be to use the server software header with a version, but it's also pretty loose as well.
Grahame Grieve (Dec 03 2020 at 21:11):
@Cooper Thompson I would think that the patch version of software is specifically for rolling the API over.
Peter Jordan (Dec 03 2020 at 22:36):
Ultimately, The Robustness Principlewill need to be applied by clients in any large health information exchange eco-system in which low-level data variations of the kind described by @lychenus are bound to occur. We see this all the time in NZ when on-boarding new applications to national systems or from new users of existing products.
lychenus (Dec 04 2020 at 06:02):
yes, i guess its slightly different issues but the solution should be the same. now before it is defined somewhere (or if the conclusion is that there wouldn't be any definition, you-do-your-thing), there would be a "look-at-the-new-ver" thing somewhere.
Michele Mottini (Dec 04 2020 at 15:07):
Seconding Peter: it is true that there can be changes in a FHIR implementation that break clients, but only if the clients were brittle to begin with: the variations that Cooper describe are all within what US Core allows, so a client for US Core should be able to handle them without having to version end point. (and same for every other possible profile / implementation guide / just base specs).
So @lychenus instead of trying to version thing I'd tell clients 'server implement FHIR version x with these profiles' and leave it at that - and they have to be robust to all variations within those profiles.
Cooper Thompson (Dec 07 2020 at 14:14):
I don't think the issue is that client aren't brittle (due to poor design) or not robust. The issue is that some applications just need very specific data, and need to program for it, and if the EHR moves that data around, then app needs to know about the movement. If your app is simple and just pulls data and displays it to end users, you can be very general. But if you have an infection control system that cares very specifically about the details of the isolates, methods, and sensitivities of a culture, you do really have to pay close attention to the structure and content of the FHIR resources, and even small changes may need review and re-testing.
Last updated: Apr 12 2022 at 19:14 UTC
