Lesson 0011 · FHIR · Modul REST · ±22 menit

Error: OperationOutcome. Discovery: CapabilityStatement

Membaca error dari server FHIR, dan menanyakan apa yang didukung server

Target lesson ini: Anda bisa menjawab "Apa yang ada di body error FHIR, dan apa beda 400 dan 422? Bagaimana tahu resource dan interaksi apa yang didukung server?" tanpa catatan: OperationOutcome.issue (severity, code, expression) dan GET [base]/metadata.

Sebelumnya, di lesson 0010, update yang kalah balapan ditolak dengan 412. Lesson terakhir modul REST ini membahas isi body error seperti itu, dan cara mengetahui kemampuan server sebelum mulai integrasi.

1. Error: OperationOutcome. Discovery: CapabilityStatement

"In case of failure, servers SHOULD always return a body that contains an OperationOutcome resource." [1] OperationOutcome adalah "A collection of error, warning, or information messages that result from a system action", dan isinya "SHOULD be in alignment with the HTTP response code". [2] 

// 422 Unprocessable Entity
{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",                       // fatal | error | warning | information
    "code": "required",                        // dari value set IssueType
    "diagnostics": "Observation.status: minimum required = 1, but only found 0",
    "expression": ["Observation.status"]       // lokasi elemen (subset FHIRPath)
  }]
}

Elemen: [2]. Contoh kode issue.code: invalid, required, value, not-found, conflict ("Edit Version Conflict"), business-rule, security, exception [4]. Teks diagnostics di atas hanya ilustrasi; isinya bebas per server.

StatusKapan (create/update)
400"resource could not be parsed or failed basic FHIR validation rules"
404 / 410tidak dikenal / sudah dihapus
409 / 412konflik versi; If-Match tidak cocok, atau conditional create/update cocok > 1
422"the proposed resource violated applicable FHIR profiles or server business rules"

Sumber tabel: [1]. Di React: issue[].expression bisa dipetakan ke field form untuk menandai input yang salah.

CapabilityStatement "documents a set of capabilities (behaviors) of a FHIR Server for a particular version of FHIR". [3] Ambil dengan GET [base]/metadata: "A Capability Statement that specifies which resource types and interactions are supported." [1] Yang dibaca saat mulai integrasi: fhirVersion, format, rest.security (cara autentikasi, lesson 0017), dan per rest.resource: type, interaction, searchParam. [3] Padanan JS: seperti dokumen OpenAPI, tapi baku dan wajib ada di setiap server FHIR.

Latihan 1 — Error dan discovery

Latihan 2 — Ucapkan dengan suara keras (±5 menit)

Pasang timer dan jawab dengan suara keras, seolah sedang interview. Jangan buka jawaban contoh sebelum selesai.

"Server FHIR menolak request dari aplikasi Anda. Bagaimana Anda membaca error-nya, dan bagaimana Anda tahu lebih dulu apa yang didukung server itu?" (60–90 detik)
Bandingkan dengan jawaban contoh dan checklist-nya

"Kalau gagal, server SHOULD mengembalikan body OperationOutcome. Saya baca setiap issue: severity (fatal, error, warning, information), code dari value set IssueType seperti required atau conflict, diagnostics sebagai teks tambahan, dan expression, path FHIRPath sederhana ke elemen yang salah, yang saya petakan ke field form di React. Status HTTP-nya juga saya bedakan: 400 berarti body tidak bisa di-parse atau gagal validasi dasar, 422 melanggar profil atau aturan bisnis, 404 tidak dikenal, 410 sudah dihapus, 409/412 konflik versi. Supaya tidak menebak, sebelum integrasi saya panggil GET [base]/metadata: server mengembalikan CapabilityStatement berisi fhirVersion, format, rest.security, dan per resource interaction serta searchParam yang didukung. Padanannya dokumen OpenAPI, tapi baku di setiap server FHIR."

Checklist: apakah Anda menyebut…

  • body error = OperationOutcome (server SHOULD mengirimnya saat gagal)?
  • issue.severity dan issue.code (value set IssueType)?
  • issue.expression menunjuk elemen yang salah, dipetakan ke field form; diagnostics teks bebas?
  • 400 (tidak bisa di-parse / validasi dasar) vs 422 (profil / aturan bisnis)?
  • status lain: 404 vs 410, 409/412 untuk konflik versi?
  • GET [base]/metadata → CapabilityStatement: fhirVersion, format, rest.security, interaction, searchParam?

Lulus kalau minimal 4 dari 6. Review 0021 akan menanyakan salah satunya lagi.

Bacaan lanjutan (opsional, tidak dihitung dalam durasi) HL7 FHIR R4: RESTful API (http.html). Baca tabel ringkasan interaksi di atas halaman, lalu bagian create, update, "Managing Resource Contention", dan transaction/batch. Setelah itu, sekilas Search bagian modifier, prefix, chained parameters, dan _include.

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] OperationOutcome · [3] CapabilityStatement · [4] ValueSet IssueType