レッスン 8: FHIR RESTful API - CRUD、検索、履歴、およびバージョニング

HL7 FHIR - 基本から高度な医療データ標準

パート 3: FHIR RESTful API とデータ交換

xdev.asia

1. FHIR RESTful API の概要

FHIR の用途 RESTful API 主な対話パラダイムとして。各リソース タイプには、HTTP 標準に従って、独自のエンドポイントがあります。

ベース URL

https://fhir-server.example.com/fhir/r5
        ├── base URL ──────────────────┘
        
GET [base]/Patient/123           → Đọc Patient có id=123
POST [base]/Patient              → Tạo Patient mới
PUT [base]/Patient/123           → Cập nhật Patient 123
DELETE [base]/Patient/123        → Xóa Patient 123

インタラクションの概要

インタラクション	HTTPメソッド	URL	説明
読む	ゲット	[ベース]/[タイプ]/[ID]	リソースを読む
ヴレッド	ゲット	[ベース]/[タイプ]/[id]/_history/[vid]	特定のバージョンを読む
更新します。アップデート	置く	[ベース]/[タイプ]/[ID]	リソースを更新する
パッチ。パッチ	パッチ	[ベース]/[タイプ]/[ID]	部分更新
削除する	削除	[ベース]/[タイプ]/[ID]	リソースの削除
作成する	投稿	[ベース]/[タイプ]	新しいリソースを作成する
検索します。検索	取得/投稿	[ベース]/[タイプ]?params	検索
歴史。歴史	ゲット	[ベース]/[タイプ]/[id]/_history	歴史の変遷
能力	ゲット	[ベース]/メタデータ	能力に関する声明

2.作成(POST)

POST /fhir/r5/Patient HTTP/1.1
Host: fhir-server.example.com
Content-Type: application/fhir+json
Prefer: return=representation

{
  "resourceType": "Patient",
  "name": [
    {
      "family": "Nguyễn",
      "given": ["Văn", "A"],
      "text": "Nguyễn Văn A"
    }
  ],
  "gender": "male",
  "birthDate": "1990-05-15"
}

HTTP/1.1 201 Created
Location: /fhir/r5/Patient/newly-assigned-id/_history/1
ETag: W/"1"
Last-Modified: 2025-01-15T10:00:00Z
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "id": "newly-assigned-id",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2025-01-15T10:00:00.000Z"
  },
  ...
}

条件付き作成

POST /fhir/r5/Patient HTTP/1.1
If-None-Exist: identifier=http://hospital.vn/mrn|MRN12345

{...}

条件に一致する患者がいない場合にのみ作成 → 重複を避ける。

3. 読み取り(GET)

GET /fhir/r5/Patient/patient-001 HTTP/1.1
Accept: application/fhir+json

バージョン読み取り (vread)

GET /fhir/r5/Patient/patient-001/_history/3 HTTP/1.1

コンテンツのネゴシエーション

ヘッダーを受け入れる	フォーマット
アプリケーション/fhir+json	JSON (推奨)
アプリケーション/fhir+xml	XML
または、_format パラメータを使用します	?_format=json

4.更新(PUT)

PUT /fhir/r5/Patient/patient-001 HTTP/1.1
Content-Type: application/fhir+json
If-Match: W/"3"

{
  "resourceType": "Patient",
  "id": "patient-001",
  "name": [
    {
      "family": "Nguyễn",
      "given": ["Văn", "A"],
      "text": "Nguyễn Văn A"
    }
  ],
  "gender": "male",
  "birthDate": "1990-05-15",
  "telecom": [
    {
      "system": "phone",
      "value": "0901234567",
      "use": "mobile"
    }
  ]
}

If-Match: W/「3」 → 楽観的ロック。現在のバージョンが 3 の場合のみ更新してください。変更されている場合 → 409 競合。

条件付き更新

PUT /fhir/r5/Patient?identifier=http://hospital.vn/mrn|MRN12345 HTTP/1.1

{...resource body...}

5.パッチ(PATCH)

JSON パッチ (RFC 6902)

PATCH /fhir/r5/Patient/patient-001 HTTP/1.1
Content-Type: application/json-patch+json

[
  {
    "op": "add",
    "path": "/telecom/-",
    "value": {
      "system": "email",
      "value": "[email protected]",
      "use": "home"
    }
  },
  {
    "op": "replace",
    "path": "/active",
    "value": true
  }
]

FHIRPath パッチ

PATCH /fhir/r5/Patient/patient-001 HTTP/1.1
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "operation",
      "part": [
        {"name": "type", "valueCode": "add"},
        {"name": "path", "valueString": "Patient"},
        {"name": "name", "valueString": "active"},
        {"name": "value", "valueBoolean": true}
      ]
    }
  ]
}

6. 削除（DELETE）

DELETE /fhir/r5/Patient/patient-001 HTTP/1.1

FHIR サーバーは多くの場合、 論理削除 物理的に削除するのではなく、（削除済みとしてマークし、履歴に保持します）。

7. 歴史

# History của một resource
GET /fhir/r5/Patient/patient-001/_history

# History của tất cả Patient
GET /fhir/r5/Patient/_history

# History toàn server
GET /fhir/r5/_history

# Với parameters
GET /fhir/r5/Patient/patient-001/_history?_count=10&_since=2025-01-01T00:00:00Z

応答はバンドルタイプを返します 歴史。歴史 すべてのバージョンが含まれています。

8. 基本的な検索

# Tìm Patient theo tên
GET /fhir/r5/Patient?name=Nguyen

# Tìm theo giới tính
GET /fhir/r5/Patient?gender=male

# Kết hợp nhiều tham số (AND)
GET /fhir/r5/Patient?name=Nguyen&gender=male&birthdate=1990-05-15

# Tìm Observation theo Patient
GET /fhir/r5/Observation?subject=Patient/patient-001&category=vital-signs

# POST search (khi query string quá dài)
POST /fhir/r5/Patient/_search
Content-Type: application/x-www-form-urlencoded

name=Nguyen&gender=male

検索応答 (バンドル検索セット)

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 42,
  "link": [
    {
      "relation": "self",
      "url": "https://fhir-server.example.com/fhir/r5/Patient?name=Nguyen&_count=10"
    },
    {
      "relation": "next",
      "url": "https://fhir-server.example.com/fhir/r5?_getpages=uuid-abc&_pageId=2"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://fhir-server.example.com/fhir/r5/Patient/patient-001",
      "resource": {
        "resourceType": "Patient",
        "id": "patient-001"
      },
      "search": {
        "mode": "match",
        "score": 1
      }
    }
  ]
}

9. 能力に関する声明

GET /fhir/r5/metadata HTTP/1.1
Accept: application/fhir+json

能力に関する声明 (旧名: Conformance) では、FHIR サーバーの機能、つまりサポートされるリソース タイプ、インタラクション、および検索パラメーターについて説明します。

10. FHIR の HTTP ステータス コード

ステータス	意味
200 OK	読み取り/検索/更新が正常に完了しました
201 件が作成されました	正常に作成されました
204 コンテンツがありません	正常に削除されました
304 未変更	条件付き読み取り、変更なし
400 件の不正なリクエスト	リクエストは無効です
401 不正	認証されていません
403 禁止	権利なし
404 見つかりません	リソースが存在しません
409 紛争	バージョンの競合 (If-Match)
410 ゴーン	リソースが削除されました
412 前提条件が失敗しました	条件付き操作が失敗しました
422 処理できないエンティティ	検証に失敗しました (OperationOutcome)

11. まとめ

• FHIR RESTful API は HTTP 標準に準拠しています。 ポスト/取得/プット/パッチ/削除

• バージョン管理 — 更新ごとに新しいバージョンが作成され、vread と履歴を介してアクセスされます

• 条件付き操作 — 同時実行制御のための If-Match、If-None-Exist

• 検索 — 多くのパラメータ タイプ、AND/OR の組み合わせによる高い柔軟性

• 能力に関する声明 — 自己記述型サーバー機能 (機械可読)