FHIR Chat · Write APIs for different functional requirements

Stream: Argo Write

Topic: Write APIs for different functional requirements

Josh Mandel (May 05 2021 at 18:00):

We've talked about use cases that suggest functional requirement like:

in some cases data should be reviewed before being finalized in the system of record;
in some cases data should flow directly into the system of record
in all cases, clients should be able to tell the status of their submission
in all cases, authorized parties should be able to see submitted data and incorporate it into CDS, etc

One example of flexible policy to support these requirements might be saying: some clients are only permitted to submit Observations with status=preliminary, or should expect the EHR to reset any submitted data to have status=preliminary; subsequently the EHR can transition these to final or canceled (which could be automatic/instantaneous, or could happen asynchronously). Other clients might be permitted to submit final results directly.

Cooper Thompson (May 05 2021 at 20:15):

Using existing status properties would be overloading the meaning of those properties (at least in most cases I can think of). You might have an Observation that moves from prelim to final to amended independent of the holding tank transition.

Cooper Thompson (May 05 2021 at 20:35):

I do get hung up on the point of making a clear line between system of record vs. holding tank. We (Epic) do have that model today, but we are actively working to "blur" the lines in that model. Our goal is to have data be displayed and used across the system regardless of which data store it is in. The data is annotated differently for end users, and potentially weighted differently for automated processes. Information automatically derived from unreviewed data may inherit annotations. But it's all "in the EHR".

Cooper Thompson (May 05 2021 at 20:40):

Alternative functional requirements might be:

Data submitted to an EHR MAY need review before it used for some purposes.
Unreviewed data MAY be used or annotated differently within the EHR.
Submitting clients SHOULD (SHALL?) be able to interact with submitted data normally over the API, regardless of review status.
Non-submitter clients MAY be able to interact with submitted (possibly annotated) data normally over the API.

Josh Mandel (May 05 2021 at 21:09):

Yeah, I don't want to over-index on (or overload) existing statuses; just trying to sketch out the kind of interface we could provide (with existing or new properties to support it).

Re: functional requirements you've listed, Cooper:

These would leave submitting clients with no way to tell the review status of their submissions -- do you want to add something to address this, or is the gap intentional?
when you say "interact... normally over the API", is this implying that the API endpoints are the same? Like, the submitted resources are, right from the start, visible under "GET Observation?patient=123" in the same FHIR endpoint where US Core read access is supported?

Eric Haas (May 06 2021 at 01:34):

Assuming half of this doesn't matter to the client and most end user are going to send it and forget it. I don't even know if we should try to enumerate all these fine-grained functional requirements upfront. Why not just do the write and then get an operation outcome that points to a url that you can check on the status of these things, if you care. (kinda like what bulk does)

image.png

So if submitting clients SHOULD (SHALL?) be able to get the data. if they can't then they go "what the hell?... oh s*** where is that url again???"

Josh Mandel (May 06 2021 at 01:38):

I don't even know if we should try to enumerate all these fine-grained functional requirements upfront.

Agreeing on the requirements is how we'll assess whether an API proposal meets them ;-)

Josh Mandel (May 06 2021 at 01:41):

Why not just do the write and then get an operation outcome that points to a url that you can check on the status of these things, if you care. (kinda like what bulk does)

Does "do the write" mean just "POST Observation" to the regular FHIR API endpoint? If so, we'd need to define new async semantics for POSTing a resource in FHIR, and define the status API, state machine, etc for how you "check on the status". That's all fine, if we need asynchronous pre-acceptance review. It's structurally very similar to using a Task (and indeed, if we were going to go this route, I'd suggest Task is a good fit).

Eric Haas (May 06 2021 at 03:09):

That's all fine, if we need asynchronous pre-acceptance review. It's structurally very similar to using a Task (and indeed, if we were going to go this route, I'd suggest Task is a good fit).

What I heard today was that yes we wanted to know the status on the write. I don't see how checking on status can be synchonrous or not require human intervention and I made the same point as above in two weeks ago in my notes on patterns. But, I sense reluctance to using Task.

Eric Haas (May 06 2021 at 03:14):

Does "do the write" mean just "POST Observation" to the regular FHIR API endpoint?

The survey showed nobody is doing this. ( I thought it sounded reasonable but it went over like a lead balloon) and does it solve anything on status updates?

Eric Haas (May 06 2021 at 03:17):

Trying to define all the nuanced different write types is like catching a greased pig. we come up with different variations each week.

Eric Haas (May 06 2021 at 03:18):

We kind of agreed that the writer should be able to fetch it. but beyond that I don't know what we got.

Eric Haas (May 06 2021 at 03:21):

sometimes it is reviewed, sometimes not
sometimes it is accessible and used by others sometimes not
it may be annoted as unreviewed

Josh Mandel (May 06 2021 at 03:56):

I think the easiest way to say it is that clients need to be able to understand disposition -- if something has been incorporated into the EHR, or rejected from it, or is still in limbo.

John Moehrke (May 06 2021 at 12:23):

AuditEvent or Provenance can do that.

John Moehrke (May 06 2021 at 12:24):

I think we should have a logical distinction between the read-from-EHR and the write-to-EHR. Some might have one endpoint, others different. but logically treating them that way will work for both kinds.

John Moehrke (May 06 2021 at 12:27):

Was there discussion of how it might look different when the holding-tank is a (a) stepping stone where the data are copied to a final resting place where clinicians use them and thus a patient read would find them, from (b) the final resting place where clinicians see/use them there. REST should not care, but in the (a) case the write response location might not be the final location, so patient write app might get confused if it persists as full URLs the write response id.

Eric Haas (May 06 2021 at 14:02):

John Moehrke said: