Tiga level $export; alur kick-off → 202 → polling → manifest

Sebelumnya, Review 1 menutup modul Fondasi dan Resource. Modul ini membahas JSON massal: dari "ekspor jutaan resource" sampai "insert ke database tanpa kehabisan memori". Lesson ini mulai dari sisi server FHIR: endpoint $export dan alur asinkronnya.

Semua fakta Bulk Data di lesson ini diambil dari Bulk Data Access IG v2.0.0 (STU 2), yang dibangun di atas FHIR R4. Halaman IG itu sendiri mencatat bahwa versi 3.0.0 sudah menggantikannya ^[1]; alur intinya sama, tapi sebutkan versinya kalau interviewer bertanya detail. Search dan paging biasa ada di lesson 0008 dan 0009; autentikasi SMART Backend Services dibahas di lesson 0019. Lesson ini tanpa lab: potongan HTTP, JSON, dan TypeScript hanya untuk dibaca dan dijelaskan.

1. Kenapa bukan search biasa: tiga level $export

Search dengan paging (GET Observation?_count=1000 lalu ikuti link next) cocok untuk layar aplikasi, bukan untuk jutaan resource: satu request per halaman, dan Anda yang mengatur semuanya. Bulk Data $export membalik perannya: server menyiapkan file di belakang, client mengambil hasilnya nanti. Operasi ini "initiates the asynchronous generation of a requested export dataset - whether that be data for all patients, data for a subset (defined group) of patients, or all FHIR data in the server." ^[1]

Kutipan tabel: ^[1]. Untuk level Patient dan Group, Patient Compartment dipakai sebagai acuan resource yang dikembalikan; resource pendukung seperti Organization dan Practitioner MAY ikut.

Tiga hal yang perlu disebut saat menjelaskan kick-off:

• Asinkron. Header Prefer: respond-async: "Currently, only a value of respond-async is supported. A client SHOULD provide this header." Accept di kick-off hanya menentukan format OperationOutcome (application/fhir+json). ^[1]
• GET wajib, POST opsional. "A server SHALL support GET requests and MAY support POST requests that supply parameters using the FHIR Parameters Resource." ^[1]
• Auth server-ke-server. Tidak ada user yang login: "implementers SHOULD implement OAuth 2.0 access management in accordance with the SMART Backend Services Authorization Profile", dan server "SHALL limit the data returned to only those FHIR resources for which the client is authorized." ^[1] Detail client credentials + JWT di lesson 0019.

Endpoint dan header kick-off sudah jelas. Berikutnya: apa yang terjadi setelah server menerima kick-off.

2. Alur asinkron: kick-off → 202 → polling → manifest

GET [base]/Patient/$export?_type=Patient,Observation&_since=2026-10-25T00:00:00Z
Accept: application/fhir+json
Prefer: respond-async
Authorization: Bearer eyJhbGciOi…          ← token dari SMART Backend Services (0019)

HTTP/1.1 202 Accepted
Content-Location: https://fhir.example.org/bulkstatus/42   ← URL status untuk polling

GET https://fhir.example.org/bulkstatus/42
  → 202 Accepted           X-Progress: "50% complete"   Retry-After: 120
  → 429 Too Many Requests  Retry-After: 300              (kalau polling terlalu sering)
  → 200 OK                 Expires: …   Content-Type: application/json   + body manifest
  → 4XX/5XX                body OperationOutcome          (export gagal)

• Kick-off sukses: "HTTP Status Code of 202 Accepted" plus "Content-Location header with the absolute URL of an endpoint for subsequent status requests (polling location)". Gagal (mis. parameter tidak didukung): 4XX/5XX dengan body OperationOutcome. ^[1]
• Polling: "Clients SHOULD follow an exponential backoff approach when polling for status." Retry-After berisi detik (mis. 120) atau http-date. Kalau client terlalu sering, server "SHOULD respond with a 429 Too Many Requests status code in addition to a Retry-After header". Selama berjalan: 202, opsional X-Progress (teks bebas < 100 karakter). ^[1]
• Export lain masih jalan: server yang ingin menolak export baru SHOULD membalas 429 + Retry-After juga. ^[1]
• Batal: DELETE ke URL status → 202; setelah itu polling ke URL yang sama SHALL menghasilkan 404 + OperationOutcome. ^[1]

Versi TypeScript singkat dari sisi client (untuk dibaca, bukan dijalankan):

async function waitForManifest(statusUrl: string, token: string): Promise<Manifest> {
  let delay = 10;                                          // detik
  for (;;) {
    const res = await fetch(statusUrl, {
      headers: { Accept: "application/json", Authorization: `Bearer ${token}` },
    });
    if (res.status === 200) return (await res.json()) as Manifest;   // manifest kecil: json() aman
    if (res.status !== 202 && res.status !== 429) {
      throw new Error(`export gagal: ${res.status}`);     // body: OperationOutcome
    }
    const retryAfter = Number(res.headers.get("Retry-After"));       // http-date → NaN
    delay = retryAfter > 0 ? retryAfter : Math.min(delay * 2, 600);  // hormati server, else backoff
    await new Promise(r => setTimeout(r, delay * 1000));
  }
}

Padanan yang mungkin Anda kenal: pola "job + status URL" yang sama dengan antrean job (BullMQ) atau API laporan asinkron. IG menyebutnya "FHIR Asynchronous Request Pattern". ^[1]

Berikutnya, lesson 0014: isi manifest, format NDJSON, parameter _type/_since, dan kenapa file hasilnya tidak boleh di-JSON.parse sekaligus.

Istilah: GLOSSARY.md (bagian "Bulk Data dan JSON skala besar") · Indeks: semua lesson FHIR

Ada yang belum jelas? Tanyakan ke saya (agent) di terminal, misalnya: "apa beda Patient/$export dan Group/[id]/$export untuk use case analitik?", "bagaimana menulis hasil export ke S3 dengan backpressure yang benar?", atau "kapan lebih baik memakai worker thread daripada streaming?"

Sumber: [1] Bulk Data Access IG v2.0.0 (STU 2): Export