Merge pull request #369 from HL7/async-pattern-alignment

Align async export operations to the simplified async interaction pattern

Author: niquola

input/fsh/operations.fsh

@@ -444,7 +444,7 @@ Instance: SQLQueryExport
 Usage: #definition
 InstanceOf: OperationDefinition
 Title: "SQLQuery Export"
-Description: "Export SQLQuery Library results asynchronously using the FHIR Asynchronous Bulk Data Request Pattern."
+Description: "Export SQLQuery Library results asynchronously using the FHIR Asynchronous Interaction Request Pattern."
 
 * id = "SQLQueryExport"
 * url = "http://sql-on-fhir.org/OperationDefinition/$sqlquery-export"

input/pagecontent/OperationDefinition-SQLQueryExport-intro.md

@@ -1,4 +1,4 @@
-Export SQLQuery Library results asynchronously using the FHIR Asynchronous Bulk Data Request Pattern.
+Export SQLQuery Library results asynchronously using the FHIR Asynchronous Interaction Request Pattern.
 
 **Use Cases:**
 
@@ -19,8 +19,9 @@ Export SQLQuery Library results asynchronously using the FHIR Asynchronous Bulk
 
 1. Client sends request with `Prefer: respond-async` header
 2. Server returns `202 Accepted` with `Content-Location` polling URL
-3. Client polls for status until the poll returns `200 OK` with the manifest in the body
-4. Client downloads exported files from the `output.location` URLs in the manifest
+3. Client polls for status until the poll returns `303 See Other` with the result URL in the `Location` header
+4. Client fetches the result URL, which returns the manifest with `200 OK`
+5. Client downloads exported files from the `output.location` URLs in the manifest
 
 This operation combines the query source and parameter binding from
 [`$sqlquery-run`](OperationDefinition-SQLQueryRun.html) with the asynchronous

input/pagecontent/OperationDefinition-SQLQueryExport-notes.md

@@ -4,22 +4,17 @@
 
 #### Asynchronous Pattern
 
-This operation follows the [FHIR Asynchronous Bulk Data Request Pattern](https://www.hl7.org/fhir/async-bulk.html); the completion response is specified once in [Common Operation Behavior — Asynchronous Delivery](operations-common.html#asynchronous-delivery):
+This operation follows the [FHIR Asynchronous Interaction Request Pattern](https://build.fhir.org/ig/HL7/api-incubator-ig/branches/simplified-async-interaction/async-interaction.html); the asynchronous flow is specified once in [Common Operation Behavior - Asynchronous Delivery](operations-common.html#asynchronous-delivery):
 
 1. Client sends request with `Prefer: respond-async` header and query source parameters
 2. Server returns `202 Accepted` with `Content-Location` header pointing to status URL
 3. Client polls the status URL for export progress
 4. Server responds with `202 Accepted` while export is in progress (MAY include interim results)
-5. Upon completion, the status poll returns `200 OK` with the manifest `Parameters` resource (`exportId`, `status`, `output`, …) **in the response body**
-6. Client downloads the exported files from the `output.location` URLs in the manifest
+5. Once the export has finished (successfully or not), the status poll returns `303 See Other` with a `Location` header carrying the result URL and an empty body
+6. Client fetches the result URL; a successful export returns `200 OK` with the manifest `Parameters` resource (`exportId`, `status`, `output`, …), and a failed export returns the error status code with an `OperationOutcome`
+7. Client downloads the exported files from the `output.location` URLs in the manifest
 
-**Note**: This operation uses a FHIR `Parameters` resource as the manifest instead of the Bulk Data JSON manifest object to:
-
-- Provide structured status reporting and metadata
-- Allow extensible output metadata specific to export operations
-- Maintain consistency with other FHIR operations
-
-**Note**: Completion is signalled by `200 OK` with the manifest in the body of the status-poll response, as in the FHIR Asynchronous Bulk Data Request Pattern. The operation does not use a `303 See Other` redirect to a separate result resource, so standard Bulk Data clients interoperate without special handling.
+The result resource for this operation is the manifest `Parameters` resource described under [Output Parameters](#output-parameters). Clients MUST treat the status and result URLs as opaque values.
 
 ##### Async Flow Diagram
 
@@ -43,11 +38,17 @@ sequenceDiagram
     rect rgb(240, 255, 240)
     Note over C,S: Step 3: Completion
     C->>S: GET /status/abc123
+    S-->>C: 303 See Other<br/>Location: /result/abc123<br/>(empty body)
+    end
+
+    rect rgb(255, 255, 240)
+    Note over C,S: Step 4: Result fetch
+    C->>S: GET /result/abc123
     S-->>C: 200 OK<br/>Body: Parameters{status: completed, output: [{name, location}]}
     end
 
     rect rgb(255, 248, 240)
-    Note over C,S: Step 4: Download
+    Note over C,S: Step 5: Download
     C->>S: GET /export/abc123/bp-results.csv
     S-->>C: 200 OK<br/>Content-Type: text/csv<br/>Body: patient_id,systolic,...
     end
@@ -74,6 +75,8 @@ sequenceDiagram
     participant S as Server
 
     C->>S: GET /status/abc123
+    S-->>C: 303 See Other<br/>Location: /result/abc123<br/>(empty body)
+    C->>S: GET /result/abc123
     S-->>C: 500 Internal Server Error<br/>Body: OperationOutcome{severity: error, diagnostics: ...}
 ```
 
@@ -101,16 +104,20 @@ Optional filtering parameters:
 
 ##### Status Request
 
-- `Accept` (recommended) - Specifies the format of the status response, including the completion (`200 OK`) response that carries the manifest
+- `Accept` (recommended) - Specifies the format of interim status responses and error responses on the status URL; the completing poll returns `303 See Other` with an empty body
+
+##### Result Request
+
+- `Accept` (recommended) - Specifies the representation of the result: the manifest `Parameters` resource on success, or the `OperationOutcome` on failure
 
 ##### Header Scope
 
-Each status-poll request's headers apply to **that poll's response**. Because
-completion is delivered as `200 OK` with the manifest in the body of the
-status-poll response (there is no separate result resource), the `Accept` header
-sent on the completing poll governs the representation of the manifest. This
-allows a client to negotiate a different representation for interim status
-responses (e.g. minimal JSON) than for the final manifest if it chooses.
+Each request's headers apply to **that request's response**. Because
+completion is delivered as `303 See Other` with an empty body, the `Accept`
+header that governs the representation of the manifest is the one sent on the
+result `GET`, not the one sent on the completing status poll. This allows a
+client to negotiate a different representation for interim status responses
+(e.g. minimal JSON) than for the final manifest if it chooses.
 
 #### Parameters
 
@@ -241,9 +248,10 @@ SQLQuery profile for the binding rules and the mapping from
 
 #### Output Parameters
 
-Output parameters appear in the **completion response** — the `200 OK`
-status-poll response that carries the manifest. They are not present in the
-`202 Accepted` responses returned while the export is still in progress.
+Output parameters form the **manifest** - the `Parameters` resource returned
+with `200 OK` from the result URL after the completing poll's `303 See Other`
+redirect. They are not present in the `202 Accepted` responses returned while
+the export is still in progress.
 
 ##### Export Identifiers
 
@@ -310,21 +318,21 @@ For large exports, servers MAY partition the output into multiple files. When pa
 
 ```json
 {
-    "name": "output",
-    "part": [
-        {
-            "name": "name",
-            "valueString": "patient_bp_results"
-        },
-        {
-            "name": "location",
-            "valueUri": "https://example.com/export/123/patient_bp_results.part1.csv"
-        },
-        {
-            "name": "location",
-            "valueUri": "https://example.com/export/123/patient_bp_results.part2.csv"
-        }
-    ]
+  "name": "output",
+  "part": [
+    {
+      "name": "name",
+      "valueString": "patient_bp_results"
+    },
+    {
+      "name": "location",
+      "valueUri": "https://example.com/export/123/patient_bp_results.part1.csv"
+    },
+    {
+      "name": "location",
+      "valueUri": "https://example.com/export/123/patient_bp_results.part2.csv"
+    }
+  ]
 }
 ```
 
@@ -336,14 +344,16 @@ Clients MUST download all parts to obtain the complete dataset.
 
 The $sqlquery-export operation uses standard HTTP status codes to indicate the outcome:
 
-| Status Code               | Description          | When to Use                                                          |
-| ------------------------- | -------------------- | -------------------------------------------------------------------- |
-| 202 Accepted              | In Progress          | Export request accepted or still in progress during polling          |
-| 200 OK                    | Complete             | Export complete; the status-poll response body carries the manifest  |
-| 400 Bad Request           | Client Error         | Invalid parameters, unsupported parameters, missing required headers |
-| 404 Not Found             | Not Found            | SQLQuery Library not found, or cancelled export status URL           |
-| 422 Unprocessable Entity  | Business Logic Error | Valid request but query is invalid or cannot be executed             |
-| 500 Internal Server Error | Server Error         | Unexpected server error; on a status poll, indicates operation failure |
+| Status Code               | Description          | When to Use                                                                         |
+| ------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
+| 202 Accepted              | In Progress          | Export request accepted, still in progress during polling, or cancellation accepted |
+| 303 See Other             | Job Finished         | Export finished (successfully or not); `Location` header carries the result URL     |
+| 200 OK                    | Result Available     | Result URL returns the manifest `Parameters`; download URLs return the files        |
+| 400 Bad Request           | Client Error         | Invalid parameters, unsupported parameters, missing required headers                |
+| 404 Not Found             | Not Found            | SQLQuery Library not found, or cancelled export status URL                          |
+| 422 Unprocessable Entity  | Business Logic Error | Valid request but query is invalid or cannot be executed                            |
+| 429 Too Many Requests     | Excessive Polling    | Client is polling too frequently; back off exponentially, guided by `Retry-After`   |
+| 500 Internal Server Error | Server Error         | Unexpected server error; on the result URL, the failure outcome of the export       |
 
 {:.table-data}
 
@@ -455,43 +465,51 @@ Content-Type: application/fhir+json
 
 1. **Kick-off Request**: Client sends `POST Library/$sqlquery-export` with `Prefer: respond-async` header and one or more `query` parameters.
 2. **Kick-off Response**: Server responds with:
-    - `202 Accepted` status code
-    - `Content-Location` header with the absolute URL for subsequent status requests (polling location)
-    - Parameters resource with `status` parameter set to `accepted` and `location` parameter
-    - If request is not valid or cannot be processed, server responds with `400 Bad Request` and `OperationOutcome` resource in the body.
+   - `202 Accepted` status code
+   - `Content-Location` header with the absolute URL for subsequent status requests (polling location)
+   - Parameters resource with `status` parameter set to `accepted` and `location` parameter
+   - If request is not valid or cannot be processed, server responds with `400 Bad Request` and `OperationOutcome` resource in the body.
 3. **Status Polling**: Client polls the polling location to get status of the export:
-    - **In Progress**: `202 Accepted` with optional Parameters resource for interim status
-    - **Progress Updates**: Server MAY include `X-Progress` header to indicate completion percentage
-    - **Retry-After**: Server SHOULD include `Retry-After` header to indicate when to retry
-    - **Interim Results**: Server MAY include partial/interim results in response body (implementation-defined)
-4. **Completion**: When the export is ready, the status poll returns:
-    - `200 OK` status code
-    - A `Parameters` resource in the body containing `status` = `completed`, the
-      export metadata, and the `output` entries with their download `location`s
-    - This is the same manifest a synchronous call would return; there is no
-      `303 See Other` redirect and no separate result URL
-5. **Error Handling**: If the export fails, the status poll returns the relevant
-   error status code (e.g. `500 Internal Server Error`) with an
-   `OperationOutcome` body. Polling-transport errors and operation failures are
-   distinguished by the status code on the poll response itself.
+   - **In Progress**: `202 Accepted` with optional Parameters resource for interim status
+   - **Progress Updates**: Server MAY include `X-Progress` header to indicate completion percentage
+   - **Retry-After**: Server SHOULD include `Retry-After` header to indicate when to retry
+   - **Interim Results**: Server MAY include partial/interim results in response body (implementation-defined)
+   - **Excessive Polling**: Server MAY respond with `429 Too Many Requests`; clients SHOULD apply exponential backoff
+4. **Completion**: When the export has finished - whether it succeeded or
+   failed - the status poll returns:
+   - `303 See Other` status code
+   - `Location` header with the absolute result URL
+   - An empty body
+   - The status endpoint reflects polling machinery only; it never communicates
+     the job's outcome. Clients MUST treat the status and result URLs as opaque
+     values.
+5. **Result Retrieval**: Client fetches the result URL with `GET`:
+   - **Success**: `200 OK` with the manifest `Parameters` resource in the body
+     containing `status` = `completed`, the export metadata, and the `output`
+     entries with their download `location`s
+   - **Failure**: the relevant error status code (e.g.
+     `500 Internal Server Error`) with an `OperationOutcome` body explaining
+     the failure; repeated fetches return the same outcome within the validity
+     window
 6. **Cancellation** (Recommended):
    Servers SHOULD support export cancellation via DELETE request to the status URL:
-    - Client sends `DELETE` request to the status polling URL
-    - Server responds with `202 Accepted`
-    - Subsequent status requests return `404 Not Found`
-    - Server SHOULD clean up any partial results
+   - Client sends `DELETE` request to the status polling URL
+   - Server responds with `202 Accepted`
+   - Subsequent status requests return `404 Not Found`
+   - Server SHOULD clean up any partial results
 7. **Result Lifetime**:
-   The completed status URL (which returns the manifest) and the
+   The result URL (which returns the manifest) and the
    `output.location` download URLs SHALL remain valid for at least 24 hours after
    export completion:
-    - Servers SHOULD support multiple retrievals of the completed manifest
-    - Servers MAY include an `Expires` header to indicate when the URLs expire
-    - Clients should retrieve results promptly but can retry within the validity window
+   - Servers SHOULD support multiple retrievals of the result
+   - Servers MAY include an `Expires` header to indicate when the URLs expire
+   - Clients should retrieve results promptly but can retry within the validity window
 8. **Access Control**:
-   Servers SHALL protect status and download URLs with appropriate access controls:
-    - Same authorization context as the original request, OR
-    - Non-guessable URLs (e.g., cryptographically random tokens)
-    - Unauthorized access attempts return `401 Unauthorized` or `403 Forbidden`
+   Servers SHALL protect status, result, and download URLs with appropriate access controls:
+   - Same authorization context as the original request (servers SHOULD limit
+     access to the client that initiated the export), OR
+   - Non-guessable URLs (e.g., cryptographically random tokens)
+   - Unauthorized access attempts return `401 Unauthorized` or `403 Forbidden`
 9. **File Download**: Client downloads the output from URLs in the `output.location` parameters.
 
 #### Examples
@@ -703,7 +721,23 @@ Accept: application/fhir+json
 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
 ```
 
-The status poll returns `200 OK` with the manifest in the body; there is no redirect:
+The export has finished, so the status poll returns `303 See Other` with the result URL in the `Location` header and no body:
+
+```http
+HTTP/1.1 303 See Other
+Location: https://example.com/fhir/export/550e8400-e29b-41d4-a716-446655440000/result
+```
+
+**Step 6: Fetch the Result**
+
+Client fetches the result URL; the manifest `Parameters` resource is returned:
+
+```http
+GET /fhir/export/550e8400-e29b-41d4-a716-446655440000/result HTTP/1.1
+Host: example.com
+Accept: application/fhir+json
+Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
+```
 
 ```http
 HTTP/1.1 200 OK
@@ -758,7 +792,7 @@ Expires: Wed, 04 Mar 2026 14:30:42 GMT
 }
 ```
 
-**Step 6: Download Files**
+**Step 7: Download Files**
 
 Client downloads each file: