HTTP の Prefer ヘッダー

本仕様は拡張バッカス・ノール形式（ABNF）を使用します（[RFC5234]）。さらに、[RFC7230] の Sections 3.2.1 および 3.2.4 で定義される "token"、"word"、"OWS"、"BWS" ルールおよび #rule 拡張、並びに [RFC7231] の Section 8.1.3 で定義される "delta-seconds" ルールを参照によって含めます。

1. もしリクエストの処理に 10 秒を超える時間がかかる場合、非同期処理のために 202 (Accepted) 応答を返す。未定義の "priority" プリファレンスも指定されています：

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10
Prefer: priority=5

{...}

2. 寛容（lenient）処理を使用する例：

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: Lenient

{...}

3. return=minimal プリファレンスに未定義の任意パラメータを付与する例：

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal; foo="some parameter"

{...}

"respond-async" プリファレンスはクライアントがサーバーに対して非同期に応答することを好むことを示します。例えば、応答の生成にサーバー側で任意のしきい値を超える時間がかかる場合、サーバーは "respond-async" を尊重して 202 (Accepted) 応答を返すことができます。

ABNF:

  respond-async = "respond-async"
      

"respond-async" の主な動機は、クライアントが非同期応答を処理する能力およびその好みをサーバーに伝えることで、非同期処理の運用を容易にすることです。

"respond-async" プリファレンスを指定するリクエストの例：

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async

{Data}

202 (Accepted) を使用した非同期応答の例：

HTTP/1.1 202 Accepted
Location: http://example.org/collection/123

202 (Accepted) レスポンスは [RFC7231] によって定義されていますが、いつどのようにこの応答コードを使うか、また処理の最終結果を決定する手続きについてはほとんど指針がありません。したがって、サーバーが非同期応答をサポートするか否か、およびその方法は実装依存であり本仕様の範囲外と見なされます。

"return=representation" プリファレンスは、クライアントが成功したリクエストへの応答にリソースの現在の状態を表すエンティティを含めることをサーバーに望むことを示します。

一方 "return=minimal" プリファレンスは、クライアントが成功したリクエストに対してサーバーに最小限の応答のみを返すことを望むことを示します。通常、そのような応答は 204 (No Content) ステータスを利用しますが、0 長のレスポンスエンティティを伴う 200 (OK) のような他のコードも適切に使用され得ます。どの応答が適切な最小応答であるかの判断は完全にサーバーの裁量です。

ABNF:

  return = "return" BWS "=" BWS ("representation" / "minimal")
      

"return=representation" を尊重する場合、返される表現はリクエストの効果的な要求 URI の表現ではない可能性があります。そのような場合、返された表現の URI を特定するために Content-Location ヘッダを使用できます。

"return=representation" プリファレンスは、クライアントとサーバー間の通信を最適化し、変更後のリソースの現在の表現を取得するための追加の GET リクエストの必要性を排除する手段を提供することを意図しています。

POST や PUT のような変更リクエストを正常に処理した後、サーバーは操作の状態を記述するエンティティ、または変更されたリソース自体の表現のいずれかを返すことを選択できます。返すエンティティの種類の選択はサーバーの裁量ですが、"return=representation" および下で定義する "return=minimal" は、応答を構築する際にクライアントの好みを考慮に入れることを可能にします。

"return=representation" を指定するリクエストの例：

PATCH /item/123 HTTP/1.1
Host: example.org
Content-Type: application/example-patch
Prefer: return=representation

1c1
< ABCDEFGHIJKLMNOPQRSTUVWXYZ
---
> BCDFGHJKLMNPQRSTVWXYZ

リソース表現を含む応答の例：

HTTP/1.1 200 OK
Content-Location: http://example.org/item/123
Content-Type: text/plain
ETag: "d3b07384d113edec49eaa6238ad5ff00"

BCDFGHJKLMNPQRSTVWXYZ

対照的に "return=minimal" は、リクエスト後にサーバーがクライアントに返すデータ量を削減できます。これは、帯域が限られたモバイル端末との通信や、クライアントが処理結果について成功したかどうか以上の情報を不要とする場合に有用です。

"return=minimal" を指定するリクエストの例：

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal

{Data}

最小限の応答の例：

HTTP/1.1 201 Created
Location: http://example.org/collection/123

"return=minimal" と "return=representation" は相互に排他的な指示です。単一のリクエストで両方を含めることが意味をなす状況は想定されません。そのようなリクエストはおそらくクライアントのコーディングエラーの結果です。そのため、両方を含むリクエストはいずれも指定されていないかのように扱うことができます。

"wait" プリファレンスは、クライアントがサーバーがリクエストを受け取ってから応答を生成するのにかかると予想する最大時間（秒）を設定するために使用できます。応答の生成が指定時間を超える場合、サーバーやプロキシは非同期処理モデルを選択し、例えば 202 (Accepted) を返すことができます。

ABNF:

  wait = "wait" BWS "=" BWS delta-seconds
      

HTTP メッセージはネットワークを横断し中継者によって処理される時間があることに注意することが重要です。これによりクライアントが応答を待つ合計時間は、サーバーが処理に要する時間に加えて増加します。厳密なタイミング要件を持つクライアントはこれらの要素を見積もり、wait 値を適切に調整できます。

他のプリファレンスと同様に "wait" プリファレンスは無視される可能性があります。クライアントは自分が待てる時間を超えたリクエストを放棄することができます。

例えば、次のリクエストを受け取ったサーバーは、処理に 10 秒以上かかる場合は非同期的に応答することを選ぶかもしれません：

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10

{Data}

"handling=strict" と "handling=lenient" のプリファレンスは、リクエスト処理中に発生し得るエラー条件をサーバーがどのように扱うべきかについて、クライアントが希望する方針を（サーバーの裁量で）示します。例えば、リクエストのペイロードにいくつかの小さな構文的または意味的エラーが含まれるが、サーバーがそれを理解して正常に処理できる場合、リクエストを拒否して適切な 4xx エラーで応答するか、処理を進めるかの判断が必要になります。"handling=strict" は、個々のエラーが回復可能であってもクライアントがリクエストを拒否して欲しいことを示すために使用できます。一方 "handling=lenient" は、クライアントがサーバーにリクエストの処理を試みて欲しいことを示します。

ABNF:

  handling = "handling" BWS "=" BWS ("strict" / "lenient")
    

"strict" プリファレンスを指定するリクエストの例：

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: handling=strict

"handling=strict" と "handling=lenient" は相互に排他的な指示です。単一リクエストに両方を含める状況は想定されません。そのようなリクエストはクライアント実装の誤りの結果である可能性が高く、そのため両方を含むリクエストはどちらも指定されていないかのように扱うことができます。

IANA は "HTTP Preferences" という新しいレジストリを "Hypertext Transfer Protocol (HTTP) Parameters" レジストリの下に作成しました。新規登録は Specification Required ポリシーを使用します（[RFC5226]）。登録されたプリファレンスの要件は Section 4 に記載されています。

登録要求は通常、必要な仕様内で公開された完成したテンプレートを含みますが、公開前に値を割り当てるために、指定専門家が仕様が公開されることに満足すれば個別に提出されたテンプレートに基づいて登録を承認することができます。指定専門家は、未登録のプリファレンスが広く展開されており迅速に登録される見込みがないと判断した場合、第三者による登録を承認することができます。

• Preference: (Section 2 の構文規則に従う Prefer リクエストヘッダーフィールドの値)
• Value: (プリファレンストークンの可能な値の列挙または説明)
• Optional Parameters: (プリファレンストークンに関連する任意パラメータとその値の列挙)
• Description:
• Reference:
• Notes: [optional]

"Value" および "Optional Parameters" フィールドは、特定のプリファレンストークン定義がそれらを定めていない場合、省略してよいです。

登録要求は <ietf-http-wg@w3.org> メーリングリストに送られるべきで、件名には明確に識別子を付けること（例："NEW PREFERENCE - example"）。要求後最大 14 日以内に指定専門家は承認または却下を決定し、その決定をレビューリストと IANA に通知します。却下には説明と、可能ならば要求を成功させるための提案を含めるべきです。

専門家レビュー担当者は次を確保するものとします：

• 要求されたプリファレンス名が Section 2 の token ルールに従っており、他の登録済みプリファレンス名と同一でないこと。
• 関連する値、パラメータ名、および値が Section 2 の ABNF 構文に従っていること。
• 名前がプリファレンスの特異性に適切であること。すなわち、意味が特定アプリケーションに非常に特化している場合は名前もそれを反映すべきで、より一般的な名前はより一般的な用途のために利用可能にしておくこと。
• 要求されたプリファレンスがサーバー、クライアント、または中継者を正常な処理に必要な挙動に制約しないこと。
• プリファレンスを定義する仕様文書が、プリファレンスの使用に関する適切かつ完全なセキュリティ考慮の議論を含んでいること。

• Preference: respond-async
• Description: クライアントがリクエストに対してサーバーが非同期に応答することを好むことを示す。
• Reference: [this specification], Section 4.1

• Preference: return
• Value: "minimal" または "representation" のいずれか
• Description: 値が "minimal" の場合、サーバーがリクエストに対して最小限の応答を返すことをクライアントが好むことを示す。値が "representation" の場合、サーバーがリクエストに対してリソースの現在状態の表現を含めることをクライアントが好むことを示す。
• Reference: [this specification], Section 4.2

• Preference: wait
• Description: クライアントが、サーバーがリクエストを受け取ってから処理するのにかかると予想する時間の上限を示す。
• Reference: [this specification], Section 4.3

• Preference: handling
• Value: "strict" または "lenient" のいずれか
• Description: 値が "strict" の場合、クライアントはサーバーが厳格な検証とエラー処理を適用することを望む。値が "lenient" の場合、クライアントはサーバーが寛容な検証とエラー処理を適用することを望む。
• Reference: [this specification], Section 4.4

7.1. 規範的参考文献

[RFC2119]

Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.

[RFC3864]

Klyne, G., Nottingham, M., and J. Mogul, “Registration Procedures for Message Header Fields”, BCP 90, RFC 3864, September 2004, <http://www.rfc-editor.org/info/bcp90>.

[RFC5226]

Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs”, RFC 5226, May 2008, <https://www.rfc-editor.org/info/rfc5226>.

[RFC5234]

Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF”, STD 68, RFC 5234, January 2008, <https://www.rfc-editor.org/info/rfc5234>.

[RFC7230]

Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing”, RFC 7230, June 2014.

[RFC7231]

Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content”, RFC 7231, June 2014.

7.2. 参考情報

[RFC5023]

Gregorio, J., Ed. and B. de hOra, Ed., “The Atom Publishing Protocol”, RFC 5023, October 2007, <https://www.rfc-editor.org/info/rfc5023>.