R6 Ballot (3rd Draft)

This page is part of the FHIR Specification v6.0.0-ballot3: Release 6 Ballot (3rd Draft) (see Ballot Notes). The current version is 5.0.0. For a full list of available versions, see the Directory of published versions

FHIR Infrastructure icon Work Group Maturity Level: 1 Standards Status: Draft

Implementation Note: The FHIR Asynchronous Interaction Request Pattern API is under active development. Participate in design discussions at chat.fhir.org icon

All of the interactions defined in the RESTful API are described as synchronous operations - that is, the client makes a query and waits for the server to respond with the outcome in the HTTP response. This pattern is not always suitable when significant server side processing is necessary.

The asynchronous request pattern, based on rfc 7240 icon, caters to this use case and is applicable in Operations and Defined Interactions that are not processed synchronously or may take a lot of time to process. For example, servers that accept a high volume sensor data and queue it for saving, or an operation that re-indexes the data in a server to add a new search parameter. Servers may choose which interactions the pattern should be supported on (if at all).

For use cases that may return a large amount of data, see Asynchronous Bulk Data Request.

The request will support the HTTP methods, URLs, headers and other parameters that normally apply, but servers SHALL also support the Prefer header described below. The Accept header in the request will dictate the format of the Bundle Resource returned when the request completes successfully or an OperationOutcome Resource when it fails, as well any the format for any OperationOutcome Resources returned to indicate a transient polling error while the request is being processed.

For servers that support both the Bulk Data and Asynchronous Interaction patterns, the _outputFormat parameter is used to disambiguate the two: when present, the Bulk Data pattern is used. So if an _outputFormat parameter is supplied as part of the request, the server SHALL respond using the Asynchronous Bulk Data Request pattern, or if this pattern is not supported by the server for the current request type, the server SHALL return an error and OperationOutcome Resource.

  • Accept (string)

    Specifies the format of the optional OperationOutcome Resource response to the kick-off request. A client SHOULD provide this header. A server may support any subset of the Serialization Format Representations. If omitted, the server MAY return an error or MAY process the request and return a format selected by the server format.

  • Prefer (string, required)

    Specifies whether the response is immediate or asynchronous. Setting this to respond-async triggers the async pattern.

3.2.6.2.2.0.2 Response - Success
  • HTTP Status Code of 202 Accepted
  • Content-Location header with the absolute URL of an endpoint for subsequent status requests (polling location)
  • Optionally, a OperationOutcome Resource in the body
3.2.6.2.2.0.3 Response - Error (e.g. unsupported search parameter)

After an asynchronous request has been started, a client MAY send a http DELETE request to the URL provided in the Content-Location header to cancel the request. Following the delete request, the server SHOULD delete all data associated with the request and when subsequent requests are made to the polling location, the server SHALL return a 404 Not Found error and an associated OperationOutcome Resource.

Servers MAY delete the data associated with a request after some period of time has passed, either since the data became available or after a status request that returned the data. (Immediate deletion after returning the data is not recommended as it is possible the client did not receive the response.) Implementer feedback on recommended time frames for data retention are welcome. For now, policies will vary by server. Clients which wish to ensure the data is deleted after retrieval can use the Delete process. TU

3.2.6.2.3.0.1 Response - Success
  • HTTP Status Code of 202 Accepted
  • Optionally a FHIR OperationOutcome in the body
3.2.6.2.3.0.2 Response - Error

After an asynchronous request has been started, the client MAY poll the status URL provided in the Content-Location header by issuing HTTP GET requests to the location.

A client SHOULD follow an exponential backoff icon approach when polling for status. A server SHOULD supply a Retry-After icon header with a with a delay time in seconds (e.g., 120 to represent two minutes) or a http-date (e.g., Fri, 31 Dec 1999 23:59:59 GMT). When provided, a client SHOULD use this information to inform the timing of future polling requests. The server SHOULD keep an accounting of status queries received from a given client, and if a client is polling too frequently, the server SHOULD respond with a 429 Too Many Requests status code in addition to a Retry-After header, and optionally a OperationOutcome Resource with further explanation. If excessively frequent status queries persist, the server MAY return a 429 Too Many Requests status code and terminate the session. Other standard HTTP 4XX as well as 5XX status codes may be used to identify errors as mentioned.

3.2.6.2.4.0.1 Response - In-Progress
  • HTTP Status Code of 202 Accepted
  • Optionally an X-Progress header with a text description of the status of the request that is less than 100 characters. The format of this description is at the server's discretion and MAY be a percentage complete value, or MAY be a more general status such as "in progress". The client MAY parse the description, display it to the user, or log it.
3.2.6.2.4.0.2 Response - Error
  • HTTP status code of 4XX or 5XX
  • The body of the response SHOULD be a OperationOutcome Resource. If this is not possible (for example, the infrastructure layer returning the error is not FHIR aware), the server MAY return an error message in another format and include a corresponding value for the Content-Type header.

Servers SHOULD NOT use status request failures to indicate a problem processing the original request. Rather, status request failures SHOULD use a transient code from the IssueType valueset when populating the OperationOutcome Resource issue.code element to indicate to the client that it should retry the request at a later time.

3.2.6.2.4.0.3 Response - Complete
  • HTTP status of 200 OK
  • A body containing a Bundle Resource with a type of batch-response. The outcome of the requested FHIR operation SHALL be present as the first entry in the bundle. This entry contains the final result of processing the operation that was initiated by the kick-off request, including:
    • The operation's success/failure status in Bundle.entry[0].response.status
    • Any error details in Bundle.entry[0].response.outcome (as an OperationOutcome resource)
    • The created/modified resource location in Bundle.entry[0].response.location when applicable
    • The actual resource in Bundle.entry[0].resource when the server includes a resource body in the response (determined by server policy and/or client-supplied prefer header)

    Note that this is different from the initial kick-off request's response (which only returns 202 Accepted). This entry represents the final outcome of the requested operation after its asynchronous processing has completed.

The outcome of the kick-off request SHALL be present as the first entry in the bundle. A successful completion of the status request SHALL be used whenever processing has completed, regardless of whether the underlying interaction has succeeded or failed. A server SHALL use the status and outcome elements of Bundle.entry[0].response to communicate any processing errors.

When the asynchronous operation fails due to an error in the request parameters or processing, the status request returns a 200 OK with a Bundle containing the error details. For example, if a client asynchronously invokes a hypothetical $example operation but omits a required parameter: 


    {
      "resourceType": "Bundle",
      "type": "batch-response",
      "entry": [{
        "response": {
          "status": "400 Bad Request",
          "outcome": {
            "resourceType": "OperationOutcome",
            "issue": [{
              "severity": "error",
              "code": "required",
              "details":{ "text": "Required parameter 'subject' missing" }
            }]
          }
        }
      }]
    }

When the asynchronous operation succeeds and creates or modifies a single resource, the status request returns a 200 OK with a Bundle containing the operation result including the resource location and optionally the resource itself: 


    {
      "resourceType": "Bundle",
      "type": "batch-response",
      "entry": [{
      "response": { 
        "status": "200 OK", 
        "location": "Observation/123" 
      },
      "resource": { 
        "resourceType": "Observation", 
        "id": "123" 
        // ... additional fields snipped for brevity 
      }
      }]
    }

When the asynchronous operation returns multiple resources (such as a search operation), the status request returns a 200 OK with a Bundle containing the operation result as a nested Bundle: 


    {
      "resourceType": "Bundle",
      "type": "batch-response",
      "entry": [
      {
        "response": { "status": "200 OK" },
        "resource": {
          "resourceType": "Bundle",
          "type": "searchset",
          "entry": [
            {
              "resource": { 
                "resourceType": "Observation", 
                "id": "123" 
                // ... additional fields snipped for brevity 
              }
            },{
              "resource": { 
                "resourceType": "Observation", 
                "id": "124" 
                // ... additional fields snipped for brevity 
              }
            }
          ]
        }
      }]
    }