Lesson 0008 · FHIR · Modul REST · ±25 menit

Interaksi REST FHIR dan search: tipe parameter, modifier, prefix

REST yang sudah Anda kenal, ditambah aturan khas FHIR yang ditanyakan di interview

Target lesson ini: Anda bisa menjawab "Apa beda 404 dan 410? Apa yang dikembalikan create? Bagaimana menulis query Observation berat badan satu pasien dalam rentang tanggal?" tanpa catatan: tabel interaksi dan status, token system|code, prefix tanggal, parameter diulang = AND, koma = OR.

Modul Resource selesai di lesson 0007: Anda sudah bisa membaca satu resource utuh. Modul REST membahas cara resource itu dibaca, dicari, dan diubah lewat HTTP.

Yang tidak perlu diajar ulang: HTTP verb, status code, JSON, fetch. Fokusnya hal yang khas FHIR. Semua klaim diambil dari spesifikasi R4 (4.0.1); kutipan berbahasa Inggris adalah teks asli spesifikasi. Istilah resource dari modul Resource: id (lesson 0004), Reference dan CodeableConcept (lesson 0005), meta (lesson 0007).

1. Interaksi REST dan status HTTP

FHIR menyebut setiap operasi dasar sebagai interaction. Polanya Express-style biasa: tipe resource di path, id logis setelahnya. JSON resmi bertipe application/fhir+json (minta lewat header Accept atau parameter _format). ^[1]

Interaction	Request	Sukses / catatan
read	`GET [base]/Patient/123`	200. Tidak dikenal → 404; sudah dihapus → 410
vread	`GET [base]/Patient/123/_history/2`	200, satu versi tertentu
create	`POST [base]/Patient`	201 + `Location: [base]/Patient/[id]/_history/[vid]`; `id` di body diabaikan
update	`PUT [base]/Patient/123`	200 (diperbarui) atau 201 (dibuat, kalau server mengizinkan id dari client)
patch	`PATCH [base]/Patient/123`	JSON Patch (`application/json-patch+json`), XML Patch, atau FHIRPath Patch
delete	`DELETE [base]/Patient/123`	200 (ada body) atau 204 (tanpa body)
search	`GET [base]/Patient?name=peter` atau `POST [base]/Patient/_search`	200 + Bundle `searchset`
history	`GET [base]/Patient/123/_history`	200 + Bundle `history`
capabilities	`GET [base]/metadata`	CapabilityStatement (lesson 0011)
batch / transaction	`POST [base]`	Bundle `batch`/`transaction` (lesson 0010)

Semua baris tabel: ^[1]. Kutipan kunci: "a GET for a deleted resource returns a 410 status code, whereas a GET for an unknown resource returns 404"; create "SHALL also return a Location header which contains the new Logical Id and Version Id"; "If an id is provided, the server SHALL ignore it."

Server menentukan id. Create memakai POST tanpa id; server mengisi id, meta.versionId, dan meta.lastUpdated. PUT ke id yang belum ada ("update as create") hanya boleh kalau server mendukungnya, diumumkan di CapabilityStatement.rest.resource.updateCreate. ^[1]
Search lewat POST (_search, body form-encoded) "has exactly the same semantics as the equivalent GET command"; berguna kalau query panjang atau tidak boleh tampil di log URL. ^[1]
Prefer: return=minimal meminta respons tanpa body, return=representation meminta resource lengkap; "Servers SHOULD honor this header." ^[1]

Latihan 1 — Interaksi dan status

Jawab tanpa scroll ke atas. Soal yang sama akan muncul lagi, diacak, di review campuran 0021.

Kuis di lesson ini adalah feedback cepat, bukan bukti penguasaan; yang dicatat hanya hasil review 0021.

2. Search: tipe parameter, modifier, prefix

Setiap resource mendefinisikan search parameter-nya sendiri, dan setiap parameter punya tipe yang menentukan sintaks nilainya. Tipe di R4: number, date, string, token, reference, composite, quantity, uri, special. ^[2] Empat yang paling sering muncul:

Tipe	Contoh parameter	Contoh query	Perilaku
string	Patient `name`, `family`	`Patient?family=sant`	"case-insensitive and accent-insensitive. May match just the start of a string." `:exact` = persis termasuk huruf besar-kecil; `:contains` = di posisi mana saja
token	Observation `code`, Patient `identifier`, `gender`	`Observation?code=http://loinc.org\|29463-7`	`[system]\|[code]`, system dicocokkan dengan `Coding.system` / `Identifier.system`. `:not` membalik, `:text` mencari teks
reference	Observation `subject`, `patient`, `encounter`	`Observation?patient=123`	menunjuk resource lain; dasar chaining dan `_include` (lesson 0009)
date	Observation `date`, Patient `birthdate`	`Observation?date=ge2024-01-01`	prefix di depan nilai; tanpa prefix = `eq`

Perilaku: ^[2]. Tipe parameter Observation (code token, date date atas Observation.effective, patient reference ke Patient): ^[3]; Patient (birthdate date, family/name string, identifier/gender token): ^[4].

Prefix (date, number, quantity)

Prefix	Arti	Prefix	Arti
`eq`	sama (default)	`ne`	tidak sama
`gt` / `lt`	lebih besar / lebih kecil	`ge` / `le`	lebih besar atau sama / lebih kecil atau sama
`sa` / `eb`	mulai setelah / berakhir sebelum	`ap`	kira-kira sama

Sumber: ^[2]. Contoh resmi rentang 2 tahun: GET [base]/Patient/23/Procedure?date=ge2010-01-01&date=le2011-12-31.

AND, OR, dan `:missing`

Parameter diulang = AND (date=ge2010-01-01&date=le2011-12-31). Nilai dipisah koma = OR (code=http://loinc.org|29463-7,http://loinc.org|3141-9). ^[2]
gender:missing=true → resource yang tidak punya nilai gender; :missing=false → yang punya. ^[2]
Parameter tak dikenal biasanya diam-diam diabaikan: "servers SHOULD ignore unknown or unsupported parameters". Header Prefer: handling=strict meminta error, handling=lenient meminta diabaikan. Parameter yang benar-benar dipakai server tercatat di link self Bundle hasil, jadi periksa itu kalau hasil terlalu banyak. ^[2]

Jebakan JS: new URLSearchParams({ date: "ge2010-01-01" }) tidak bisa memuat dua date; pakai params.append("date", …) dua kali. Dan | di token sebaiknya di-encode (%7C), yang otomatis dilakukan URLSearchParams.

Latihan 2 — Menyusun query

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

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

"Jelaskan siklus hidup satu Patient lewat REST API FHIR: request apa yang Anda kirim untuk create, read, update, delete, dan search, dan status apa yang Anda harapkan?" (60–90 detik)

Bandingkan dengan jawaban contoh dan checklist-nya

"Create: POST [base]/Patient tanpa id; server mengisi id, meta.versionId, dan meta.lastUpdated, lalu membalas 201 dengan header Location: [base]/Patient/[id]/_history/[vid]. Kalau saya mengirim id di body, server mengabaikannya. Read: GET [base]/Patient/123 → 200; kalau tidak dikenal 404, kalau sudah dihapus 410. Update: PUT [base]/Patient/123 → 200; PUT ke id yang belum ada hanya membuat resource (201) kalau server mengumumkan updateCreate di CapabilityStatement. Perubahan sebagian bisa lewat PATCH, mis. JSON Patch. Delete: DELETE [base]/Patient/123 → 200 dengan body atau 204 tanpa body. Search: GET [base]/Patient?name=peter, atau POST [base]/Patient/_search dengan semantik sama, hasilnya 200 + Bundle searchset. Semua dengan application/fhir+json."

Checklist: apakah Anda menyebut…

create = POST [base]/Patient → 201 + header Location berisi id dan versi?
server yang menentukan id; id di body create diabaikan?
read: 200, tidak dikenal 404, sudah dihapus 410?
update PUT → 200; update-as-create (201) hanya kalau server mendukung updateCreate?
delete → 200 (ada body) atau 204 (tanpa body); PATCH untuk perubahan sebagian?
search lewat GET atau POST _search, hasil Bundle searchset?

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

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

Ada yang belum jelas? Tanyakan ke saya (agent) di terminal, misalnya: "apa beda subject dan patient sebagai search parameter Observation?" atau "kapan pakai PATCH dibanding PUT di FHIR?"

Sumber (semua FHIR R4 4.0.1, diakses 2026-10-26): [1] RESTful API · [2] Search · [3] Observation: search parameters · [4] Patient: search parameters