RESTful HTTP による実装について（§2.1）

標準のリソース・セットの定義に加えて、FHIR では HTTP を用いたシンプルな RESTful による実装方法を定めています。いずれのリソース・タイプについても、同じ組み合わせのインタラクションが定義されていて、個々のリソースを、それぞれ独立して管理することができます。このリソース操作のフレームワークに対応したアプリケーションは "RESTful FHIR" にコンフォーマントであるといいます。

この RESTful フレームワークでは、トランザクションは、HTTP リクエスト／レスポンスを用いて、サーバー上のリソースに対して直接行われることに注意してください。この API では、認証や承認や監査コレクションといった機能にはそれ自身では対応していません。詳しくは、セキュリティのベージを参照してください。

ここに記述される API では、FHIR のリソースに対する一連の操作を、リソースの個々のインスタンスがリソース・タイプ別のコレクションとして管理されているものとして定義します。

定義されているインタラクションは以下の通りです：

サービス・ルート URL（§2.1.1）

サービス・ルート URL とは、このインタフェースで定義されているリソースすべてを有しているアドレスです。サービス・ルート URL は以下の形をとります：

http(s)://server[/path]

省略可能な path の部分は、最後に "/" がついても、つかなくても構いません。この仕様で定義されている各リソース・タイプには、それぞれルート URL に "/[小文字のリソース名]" 付加した URL に存在するマネージャによって管理されます。たとえば "Patient" タイプに対するリソース・マネージャは以下の URL に存在します：

http(s)://server/path/patient

すべての相対的参照は、サービス・ルート URL を基準にして行われます。このことは、あるシステムの FHIR リソースのどれかひとつでもアドレスが判明すれば、他のすべてのリソースの正しいアドレスが特定できるということに注意してください。しかしながら、アプリケーションの URL は変更される可能性があり、閉じたシステム連携範囲での FHIR の使用例の中にはリソースの送受信を行うシステムが宣言しているのとは別のシステムがリソースを発行するようなローカル設定があるので、アプリケーションがサービス・ルート URLを入れ替えなければならない場合もあります。

注意：この仕様で定義されるすべての URL （そして URL の部分を構成する id）は、すべて大文字小文字を区別します。

サーバーが、 http://server/...[id]... の形式で、ここでの id がある FHIR API の特定のインスタンスを示す可変部分であるようなパスを使うことがあることに注意してください。典型的には、id は患者を特定し、関連する情報は患者 id によって完全に区画分けされています。このような場合、FHIR API は、患者中心的な観点からすべての記録を表現していて、認証や承認は URL に含まれる id によって明示的に対象が示されます。

リソースのメタデータとバージョン管理（§2.1.2）

各リソースは、そのリソースに結びつけられた一組のリソース・メタデータ・エレメントを持ちます。メタデータは、以下のフィールドを用いて、HTTP リクエストとレスポンスとを関連づけます：

セキュリティ（§2.1.3）

HTTP セキュリティの項を参照してください。

HTTP ステータス・コード（§2.1.4）

FHIR 仕様では、個々の状況における、それぞれの HTTP ステータス・コードの使用方法について、ステータス・コードが厳密に割り当てられていてその通り正しく反映しなければならない状況と、正しいステータス・コードが決定できないことが起こりうる全ての状況をルールとして規定しています。規定以外のステータス・コードについては、規定以外の状況に応じて使用することができ、そのような具体例としては、特に、ステータス・コードやリダイレクションに関わる様々な認証が挙げられます。認証のリダイレクションはリソースそのもののロケーションの移動と解釈してはいけません。（よく見られるウェブ・プログラミング上の誤りです。）

FHIR には、具体的で詳細な機械処理可能なエラー情報を伝達する OperationOutcome リソースが定義されています。OperationOutcome は、いくつかの Operation と特定のエラー・コードの組み合わせを含む、レスポンスのコンテンツとして返されることになっています。OperationOutcome を返す時には、任意の HTTP 4xx または 5xx レスポンスに含めることができますが、そうすることは必須ではありません。これらの HTTP エラーの多くは、FHIR サーバーが載っている汎用のサーバー・フレームワークによって生成されることがあります。

コンテンツ・タイプとエンコーディング（§2.1.5）

FHIR リソースの正式な MIME タイプは application/fhir+xml （現在未登録）で、これはクライアントとサーバーの双方で使用されなければなりません。サーバーは、HTTP 仕様のセクション 12 に記述された、サーバー主導のコンテンツ・ネゴシエーションをサポートしなければなりませんが、様々な実装上の制限に対応するために、レスポンスの代替のフォーマットを MIME タイプで指定する、(?_format=) のパラメーターをサポートすることを任意で実装できます。_format パラメーターの値としては、"xml"、"text/xml" および "application/fhir+xml" については FHIR 標準の XML フォーマット、"json"、"application/json" および "application/fhir+json" については FHIR 参考の JSON フォーマットとして解釈しなければなりません。アプリケーションのコンテンツ・タイプは、バンドルと単一のリソースのどちらがやり取りされるかによっても影響されます：

FHIR は、全てのリクエストとレスポンスのボディについて UTF-8 を使用します。HTTP 仕様（セクション 3.7.1）ではデフォルトの文字エンコーディングは ISO-8859-1 と定められているので、リクエストやレスポンスは Content-Type ヘッダーの中の MIME-type の "charset" パラメーターに、明示的に UTF-8 を指定しなければなりません。リクエストでは、それに加えて Accept ヘッダーの中の charset パラメーターを指定したり Accept-Charset ヘッダーを指定することができます。

read（§2.1.6）

read インタラクションは、リソースの現在のコンテンツを読み出します。このインタラクションは下記の HTTP GET 操作で実行されます：

GET [service-url]/[resourcetype]/{@id} (?_format=mimeType)

この操作は、指定されたリソース・タイプの指定されたコンテンツのインスタンスをひとつ返します。この URL 全体はブラウザでのアクセスも受け付けます。URL の解釈を容易にするため、論理 ID の前には @ が付加されます。ID 自体の取り得る値については、ID データタイプの項に記述されています。サーバーは、レスポンスと一緒に、完全なバージョンが特定された URL（ vread の項参照）を含むコンテンツ・ロケーション・ヘッダーと、最終更新日時ヘッダーを返す必要があります。

注意：read では、未知のリソースと削除済みのリソースでは扱いが異なります：削除済みのリソースに対して行われた GET は、状態コード 410 を返す一方で、未知のリソースに対する GET は、状態コード 404 を返します。削除済みの履歴を管理しないシステムでは、削除済みのリソースを未知のリソースとして扱います。

vread（§2.1.7）

vread インタラクションは、リソースのバージョン特定読み出し操作を実行します。このインタラクションは下記の HTTP GET 操作で実行されます：

GET [service-url]/[resourcetype]/{@id}/history/{@vid} (?_format=mimeType)

この操作は、指定されたリソース・タイプの指定されたリソースの指定されたバージョンのコンテンツを含んだインスタンスをひとつ返します。

バージョン ID は、リソース ID と同じフォーマット規則に従う明示されていない ID です。バージョン ID は history 操作（後述）を行うか、read 操作で返ってきたコンテンツ・ロケーションの ID を記憶しておくか、または、コンテンツ・モデルのバージョン特定のリファレンスから得られます。もし、リファレンスされているバージョンが、リソースが削除された時点のものであれば、サーバーは状態コード 410 を返すべきです。

サーバーは、もし以前のバージョンへのアクセスを提供していない場合でも、リソースの現在のコンテンツのバージョン特定読み出しをサポートすることが推奨されています。もし、以前のバージョンへのアクセス要求があって、サーバーが以前のバージョンの読み出しをサポートしていない場合には、サーバーは 405 Method Not Allowed エラーを返すべきです。

update（§2.1.8）

注意：FHIR は、正式な HL7 標準として投票される以前の、現在開発中のドラフト仕様です。

実装者がここで定義されている内容での試験実装を行うことは歓迎されていますが、内容が事前の通知無しで変更される可能性があることを明記して下さい。