Bundle transaction vs batch, conditional create; versioning, ETag, If-Match

Sebelumnya, di lesson 0009, Anda membaca Bundle searchset hasil search. Lesson ini memakai Bundle ke arah sebaliknya, untuk mengirim banyak perubahan sekaligus, lalu membahas cara mencegah dua user saling menimpa update.

1. Bundle transaction vs batch, dan conditional create

Keduanya dikirim dengan POST [base]; body-nya Bundle dengan type transaction atau batch, dan setiap entry membawa request.method + request.url ("the HTTP action to be executed for this entry"). ^{[1] [2]}

Kutipan: ^{[1] [3]}. Untuk transaction, server "SHALL also update any references to that resource in the same bundle". Padanan JS hanya analogi perilaku, bukan klaim spesifikasi.

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    { "fullUrl": "urn:uuid:61ebe359-bfdc-4613-8bf2-c5e300945f0a",
      "resource": { "resourceType": "Patient",
                    "identifier": [{ "system": "http://rs.example.org/mrn", "value": "12345" }] },
      "request": { "method": "POST", "url": "Patient",
                   "ifNoneExist": "identifier=http://rs.example.org/mrn|12345" } },
    { "resource": { "resourceType": "Observation", "status": "final",
                    "code": { "coding": [{ "system": "http://loinc.org", "code": "29463-7" }] },
                    "subject": { "reference": "urn:uuid:61ebe359-bfdc-4613-8bf2-c5e300945f0a" } },
      "request": { "method": "POST", "url": "Observation" } }
  ]
}

Conditional create (Bundle.entry.request.ifNoneExist: "Instruct the server not to perform the create if a specified resource already exists" ^[4], atau header If-None-Exist: [search parameters] pada POST biasa) membuat import idempoten: 0 cocok → create biasa; 1 cocok → "The server ignores the post and returns 200 OK"; lebih dari 1 → 412, kriteria "not selective enough". Pola sama untuk conditional update PUT [base]/Patient?identifier=…. ^[1] Di contoh atas, kalau Patient MRN 12345 sudah ada, Observation tetap dibuat dan merujuk ke Patient lama.

Urutan pemrosesan transaction

"The outcome of processing the transaction SHALL NOT depend on the order of the resources in the transaction": server sendiri yang mengurutkan berdasarkan method. ^[1] Susun urutan yang ditetapkan spesifikasi:

2. Versioning: vread, ETag, If-Match

• Setiap update membuat versi baru; nomornya di meta.versionId dan dikirim sebagai header ETag, waktu di meta.lastUpdated sebagai Last-Modified. Version id adalah "weak" ETag, jadi berawalan W/, mis. ETag: W/"3141". ^[1]
• Lost update ("two clients update the same resource, and the second overwrites the updates of the first") "can be prevented using a combination of the ETag and If-Match header". Kalau versi di If-Match tidak cocok, "the server returns a 412 Precondition Failed status code instead of updating the resource". ^[1]
• Versioning tidak wajib: server "SHOULD provide full version support", tapi boleh tidak; cek CapabilityStatement. Untuk PATCH pun, "Clients SHOULD always consider using version specific PATCH operations". ^[1]

// Optimistic locking: sama seperti kolom version di ORM, tapi lewat header HTTP
const read = await fetch(`${base}/Patient/123`, { headers: { Accept: "application/fhir+json" } });
const etag = read.headers.get("ETag");          // W/"3"
const patient = await read.json();
patient.telecom = [{ system: "phone", value: "+62-812-0000-0000" }];

const res = await fetch(`${base}/Patient/123`, {
  method: "PUT",
  headers: { "Content-Type": "application/fhir+json", "If-Match": etag! },
  body: JSON.stringify(patient),
});
if (res.status === 412) {
  // user lain sudah menyimpan versi 4: muat ulang, tampilkan perbedaan, minta user memutuskan
}

Melihat versi lama: GET [base]/Patient/123/_history/3 (vread, satu versi) atau GET [base]/Patient/123/_history (Bundle type: "history", semua versi). ^[1]

Ringkasan untuk dicetak: Reference: REST, search, Bundle · Istilah: GLOSSARY.md (bagian "REST API")

Ada yang belum jelas? Tanyakan ke saya (agent) di terminal.

Sumber (semua FHIR R4 4.0.1, diakses 2026-10-26): [1] RESTful API · [2] Bundle · [3] CodeSystem BundleType · [4] Bundle: detailed definitions