FHIR REST API実装

このスキルは、HL7 FHIR仕様（R4/R5）に従ったFHIR RESTful APIの実装に関するガイダンスを提供します。

URLの構造

すべてのFHIR REST URLは以下のパターンに従います：

[base]/[type]/[id]

• [base]: サービスベースURL（例：https://fhir.example.org/r4）
• [type]: リソースタイプ（例：Patient、Observation）
• [id]: リソースの論理ID

URLは大文字と小文字を区別し、UTF-8エンコーディングを使用します。

コア操作

操作	HTTP	URLパターン	成功
Read	GET	[base]/[type]/[id]	200
VRead	GET	[base]/[type]/[id]/_history/[vid]	200
Create	POST	[base]/[type]	201
Update	PUT	[base]/[type]/[id]	200/201
Patch	PATCH	[base]/[type]/[id]	200
Delete	DELETE	[base]/[type]/[id]	200/204
Search	GET/POST	[base]/[type]?params	200
History	GET	[base]/[type]/[id]/_history	200
Capabilities	GET	[base]/metadata	200
Batch/Transaction	POST	[base]	200

各操作の詳細な仕様については、references/operations.mdを参照してください。

コンテントネゴシエーション

MIMEタイプ

形式	MIMEタイプ
JSON	application/fhir+json
XML	application/fhir+xml
RDF	application/fhir+turtle

レスポンス形式にはAcceptヘッダーを、リクエストボディ形式にはContent-Typeを使用します。

クライアントがヘッダーを設定できない場合、_formatクエリパラメータがAcceptよりも優先されます。

FHIRバージョン

MIMEタイプパラメータでバージョンを指定します：

Accept: application/fhir+json; fhirVersion=4.0

バージョンマッピング：1.0（R2）、3.0（R3）、4.0（R4）、4.3（R4B）、5.0（R5）。

必須ヘッダー

リクエストヘッダー

ヘッダー	目的	例
Accept	レスポンス形式	application/fhir+json
Content-Type	リクエストボディ形式	application/fhir+json
If-Match	楽観的ロック	W/"123"
If-None-Exist	条件付き作成	identifier=123
Prefer	返却設定	return=representation

レスポンスヘッダー

ヘッダー	目的	例
ETag	バージョン識別子	W/"123"
Location	新規リソースURL	[base]/Patient/123/_history/1
Last-Modified	変更時刻	RFC 7231日付形式

バージョニングと楽観的ロック

FHIRはバージョン追跡にweak ETagを使用します：

1. サーバーはレスポンスでETag: W/"[versionId]"を返す
2. クライアントは更新時にIf-Match: W/"[versionId]"を送信する
3. バージョン不一致の場合、サーバーは412 Precondition Failedを返す

CapabilityStatement.rest.resource.versioningがversioned-updateの場合、バージョン対応の更新を実装します。

エラーハンドリング

すべてのエラーに対してOperationOutcomeリソースを返します：

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "diagnostics": "Patient.birthDate: Invalid date format"
        }
    ]
}

ステータスコード

コード	意味
400	無効な構文またはバリデーション失敗
404	リソースが見つかりません
409	バージョン競合
410	リソースが削除されています
412	前提条件不符号（バージョン不一致）
422	ビジネスルール違反

Preferヘッダー

Preferでレスポンスコンテンツを制御します：

値	レスポンスボディ
return=minimal	空（ヘッダーのみ）
return=representation	フルリソース
return=OperationOutcome	バリデーション結果

非同期操作の場合、Prefer: respond-asyncを使用して202 AcceptedとステータスポーリングURLを取得します。

実装チェックリスト

サーバー実装では以下を実施すべきです：

1. /metadataにCapabilityStatementを実装する
2. コンテントネゴシエーションをサポートする（最低限JSON）
3. バージョン管理されたリソースに対して適切なETagを返す
4. 作成/更新時にLocationヘッダーを含める
5. すべてのエラーに対してOperationOutcomeを返す
6. _formatパラメータフォールバックをサポートする
7. Preferヘッダーを尊重してレスポンスコンテンツを制御する

参考資料

• operations.md: 詳細な操作仕様
• search.md: 検索パラメータおよび結果処理
• batch-transaction.md: バッチおよびトランザクション処理