Support Prefer: response-async in MedplumClient

[codyebberson]

API design question:

At present, MedplumClient methods createResource, updateResource, and patchResource return the result of the operation. This provides a clean API for the common case:

const patient = await medplum.createResource({ ... });

The client handles some special cases in update and patch, where the server returns 304 not modified, then the client returns the input, so the API contract holds.

I'm working with the Health Gorilla API, and a bunch of their FHIR endpoints require Prefer: respond-async. The API returns HTTP 202 "Accepted" with a "Content-Location" header.

We handle a version of this in our bulk export methods (thanks @tonylee80!) But I now wonder if we should try to handle this at a more general level, because arguably any FHIR call could/should support the Prefer: respond-async option.

Options:

1. Silently handle "Accepted" and "Content-Location" behind the scenes
   a. Users can pass in Prefer: respond-async in the optional headers
   b. When MedplumClient sees "Accepted" and "Content-Location", it automatically starts polling and waiting for the response
   c. Pros: "Easiest" for users? Everything just happens automatically
   d. Cons: Too much magic? The response could take hours or more before responding

const requestGroup = await client.createResource({ ... }, { headers: { Prefer: 'respond-async' }});

2. Optional args to methods to opt-in to the polling and waiting behavior
   a. Similar to option 1, but users have to opt-in

const requestGroup = await client.createResource({ ... }, undefined, { preferAsync: true });

3. New methods that make this very explicit
   a. Not all that different from Option 2, but different method would perhaps be more discoverable and less magical
   b. Function signature might also be easier to digest

const response = await client.createResourcePreferAsync({ ... });
const requestGroup = await client.pollResponse(response);

4. Use existing methods, throw a special exception, and then give another method to handle polling for the response
   a. Pros: Super explicit. Supports cases where server returns "Accepted" without client opting in
   b. Cons: ugly and verbose; might be an abuse of exceptions

try {
    const requestGroup = await client.createResource({ ... }, { headers: { Prefer: 'respond-async' }});
} catch (err) {
   if (err.type === 'Accepted') {
      const requestGroup = await client.pollResponse(err.response);
   } else {
       throw err;
   }
}

[mattwiller]

I like the developer experience of the explicit option from (2) best: good not to force developers to pass a nested object with specific implementation detail names in it for such a cross-cutting feature. One potentially important consideration in favor of the more explicit styles is how a developer might cancel or resume a long-running poll. For example, if their application needs to be restarted in the middle of a large async operation, we would probably want to provide an easy way for them to pick back up polling rather than needing to fully retry

[codyebberson]

Thanks for feedback! That makes sense.

how a developer might cancel or resume a long-running poll

This is a good question, and an interesting design challenge.

In the simple case, the long-running poll just requires a URL (from the "Content-Location" header). I don't know if that's always the case?

You could use the setInterval/clearInterval model of a timerId

You could use the AbortController model with .abort()

You could return a RequestPoller object with .start() and .stop() methods that try to wrap all of that.

Lots of different directions that could go

In the absence of an obvious easy solution, I'm also ok with exposing basic primitives that at least allow the user to do what they need. So, for example, maybe the MVP version is to just expose an option that let's the user get access to the Response object, and then they can do whatever they need to do.

const requestGroup = await client.createResource(
  { ... }, // The resource
  undefined, // Fetch options
  {
    preferAsync: true, // Sets `Prefer: respond-async` header, and handles "202 Accepted" responses
    onResponse: () => { ... }, // Optional callback for individual responses - this would allow users to grab whatever headers they want/need
  });