[要約] RFC 7240は、HTTPのPreferリクエストヘッダーとPreference-Appliedレスポンスヘッダーを定義し、クライアントがサーバーに対して特定の動作（非同期処理や最小限のレスポンスなど）を希望することを可能にします。この仕様により、クライアントはExpectヘッダーのような「必須の期待」ではなく、サーバーが無視することも可能な「オプションの好み」を伝えることができ、通信の最適化や柔軟なエラー処理が実現されます。主なPreferenceとして、非同期応答を促すrespond-async、レスポンスの表現内容を制御するreturn=representation/minimal、処理待ち時間を指定するwait、検証の厳密さを指定するhandling=strict/lenientが定義されています。
Internet Engineering Task Force (IETF) J. Snell
Request for Comments: 7240 June 2014
Category: Standards Track
ISSN: 2070-1721
Prefer Header for HTTP
HTTPのPreferヘッダー
Abstract
概要
This specification defines an HTTP header field that can be used by a client to request that certain behaviors be employed by a server while processing a request.
この仕様は、リクエストの処理中にサーバーが特定の動作を採用するよう要求するためにクライアントが使用できるHTTPヘッダーフィールドを定義します。
Status of This Memo
本文書の状態
This is an Internet Standards Track document.
これはInternet Standards Trackドキュメントです。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.
このドキュメントは、IETF（Internet Engineering Task Force）の成果物です。これは、IETFコミュニティのコンセンサスを表しています。公開レビューを受け、インターネットエンジニアリングステアリンググループ（IESG）による公開が承認されました。インターネット標準の詳細については、RFC 5741のセクション2をご覧ください。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7240.
このドキュメントの現在のステータス、エラータ、およびフィードバックの提供方法に関する情報は、http://www.rfc-editor.org/info/rfc7240 で入手できます。
Copyright Notice
著作権表示
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.
Copyright (c) 2014 IETF Trustおよびドキュメントの作成者として識別された人物。全著作権所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
この文書は、BCP 78およびこの文書の発行日に有効なIETF文書に関するIETFトラストの法的規定 (http://trustee.ietf.org/license-info) の対象となります。これらのドキュメントは、このドキュメントに関する利用者の権利と制限を説明しているため、注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、Trust Legal Provisionsのセクション4.eに記載されているSimplified BSD Licenseのテキストが含まれている必要があり、Simplified BSD Licenseに記載されているように保証なしで提供されます。
Table of Contents
目次
1. Introduction ....................................................2
1.1. Syntax Notation ............................................4
2. The Prefer Request Header Field .................................4
2.1. Examples ...................................................6
3. The Preference-Applied Response Header Field ....................7
4. Preference Definitions ..........................................8
4.1. The "respond-async" Preference .............................8
4.2. The "return=representation" and "return=minimal"
Preferences ................................................9
4.3. The "wait" Preference .....................................11
4.4. The "handling=strict" and "handling=lenient" Processing ...12
5. IANA Considerations ............................................13
5.1. The Registry of Preferences ...............................13
5.2. Initial Registry Contents .................................15
6. Security Considerations ........................................16
7. References .....................................................16
7.1. Normative References ......................................16
7.2. Informative References ....................................16
Within the course of processing an HTTP request, there are typically a range of required and optional behaviors that a server or intermediary can employ. These often manifest in a variety of subtle and not-so-subtle ways within the response.
HTTPリクエストを処理する過程で、通常、サーバーまたは仲介者が使用できる一連の必須およびオプションの動作があります。これらは、多くの場合、レスポンス内で様々な微妙な、あるいは明白な形で現れます。
For example, when using the HTTP PUT method to modify a resource -- similar to that defined for the Atom Publishing Protocol [RFC5023] -- the server is given the option of returning either a complete representation of a modified resource or a minimal response that indicates only the successful completion of the operation. The selection of which type of response to return to the client generally has no bearing on the successful processing of the request but could, for instance, have an impact on what actions the client must take after receiving the response. That is, returning a representation of the modified resource within the response can allow the client to avoid sending an additional subsequent GET request.
たとえば、リソースを変更するためにHTTP PUTメソッドを使用する場合（Atom Publishing Protocol [RFC5023]で定義されているものと同様）、サーバーには、変更されたリソースの完全な表現、または操作の正常な完了のみを示す最小限のレスポンスのいずれかを返すオプションが与えられます。クライアントにどのタイプのレスポンスを返すかの選択は、通常、リクエストの正常な処理には影響しませんが、たとえば、レスポンスを受信した後にクライアントが実行する必要があるアクションに影響を与える可能性があります。つまり、レスポンス内で変更されたリソースの表現を返すことにより、クライアントは後続の追加のGETリクエストの送信を回避できます。
Similarly, servers that process requests are often faced with decisions about how to process requests that may be technically invalid or incorrect but are still understandable. It might be the case that the server is able to overlook the technical errors in the request but still successfully process the request. Depending on the specific requirements of the application and the nature of the request being made, the client might or might not consider such lenient processing of its request to be appropriate.
同様に、リクエストを処理するサーバーは、技術的に無効または正しくない可能性があるが、依然として理解可能なリクエストの処理方法に関する決定に直面することがよくあります。サーバーがリクエストの技術的なエラーを見落としつつ、リクエストを正常に処理できる場合もあります。アプリケーションの特定の要件と行われるリクエストの性質に応じて、クライアントは、そのようなリクエストの寛大な処理が適切であると見なす場合と見なさない場合があります。
While the decision of exactly which behaviors to apply in these cases lies with the server processing the request, the server might wish to defer to the client to specify which optional behavior is preferred.
これらの場合にどの動作を適用するかを決定するのはリクエストを処理するサーバーですが、サーバーはどのオプションの動作が好ましいかをクライアントに指定させたいと考えるかもしれません。
Currently, HTTP offers no explicitly defined means of expressing the client's preferences regarding the optional aspects of handling of a given request. While HTTP does provide the Expect header -- which can be used to identify mandatory expectations for the processing of a request -- use of the field to communicate optional preferences is problematic:
現在、HTTPには、特定の要求の処理のオプションの側面に関するクライアントの好みを明示的に定義する手段はありません。HTTPはExpectヘッダーを提供しており、これはリクエストの処理に対する必須の期待を識別するために使用できますが、オプションの好みを伝達するためにこのフィールドを使用することには問題があります。
1. The semantics of the Expect header field are such that intermediaries and servers are required to reject any request that states unrecognized or unsupported expectations.
1. Expectヘッダーフィールドのセマンティクスは、仲介者やサーバーが、認識されていない、またはサポートされていない期待内容を示すリクエストを拒否する必要があるというものです。
2. While the Expect header field is end to end, the HTTP specification requires that the header be processed hop by hop. That is, every interceding intermediary that handles a request between the client and the origin server is required to process an expectation and determine whether it is capable of appropriately handling it.
2. Expectヘッダーフィールドはエンドツーエンドですが、HTTP仕様ではヘッダーをホップバイホップで処理することを要求しています。つまり、クライアントとオリジンサーバーの間でリクエストを処理するすべての仲介者は、期待内容を処理し、それを適切に処理できるかどうかを判断する必要があります。
The must-understand semantics of the Expect header make it a poor choice for the expression of optional preferences.
Expectヘッダーは理解必須（must-understand）のセマンティクスを持つため、オプションの好みを表現するには適していません。
Another option available to clients is to utilize Request URI query-string parameters to express preferences. However, any mechanism that alters the URI can have undesirable effects, such as when caches record the altered URI.
クライアントが使用できるもう1つのオプションは、リクエストURIのクエリ文字列パラメータを使用して好みを表現することです。しかし、URIを変更するメカニズムは、キャッシュが変更されたURIを記録する場合など、望ましくない影響を与える可能性があります。
As an alternative, this specification defines a new HTTP request header field that can be used by clients to request that optional behaviors be applied by a server during the processing the request. Additionally, a handful of initial preference tokens for use with the new header are defined.
別の方法として、この仕様では、リクエストの処理中にサーバーがオプションの動作を適用することを要求するためにクライアントが使用できる新しいHTTPリクエストヘッダーフィールドを定義しています。さらに、新しいヘッダーで使用するいくつかの初期設定トークンが定義されています。
In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119].
このドキュメントでは、キーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、[RFC2119]で説明されているように解釈されます。
This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234] and includes, by reference, the "token", "word", "OWS", and "BWS" rules and the #rule extension as defined within Sections 3.2.1 and 3.2.4 of [RFC7230]; as well as the "delta-seconds" rule defined in Section 8.1.3 of [RFC7231].
この仕様は、[RFC5234]の拡張バッカスナウア記法（ABNF）を使用し、[RFC7230]のセクション3.2.1および3.2.4で定義されている「token」、「word」、「OWS」、「BWS」ルール、および「#rule」拡張、ならびに[RFC7231]のセクション8.1.3で定義されている「delta-seconds」ルールを参照しています。
The Prefer request header field is used to indicate that particular server behaviors are preferred by the client but are not required for successful completion of the request. Prefer is similar in nature to the Expect header field defined by Section 6.1.2 of [RFC7231] with the exception that servers are allowed to ignore stated preferences.
Preferリクエストヘッダーフィールドは、特定のサーバー動作がクライアントによって優先されるが、リクエストが正常に完了するために必須ではないことを示すために使用されます。Preferは、[RFC7231]のセクション6.1.2で定義されているExpectヘッダーフィールドと性質が似ていますが、サーバーが指定された設定を無視できる点が異なります。
ABNF:
ABNF：
Prefer = "Prefer" ":" 1#preference
preference = token [ BWS "=" BWS word ]
*( OWS ";" [ OWS parameter ] )
parameter = token [ BWS "=" BWS word ]
This header field is defined with an extensible syntax to allow for future values included in the Registry of Preferences (Section 5.1). A server that does not recognize or is unable to comply with particular preference tokens in the Prefer header field of a request MUST ignore those tokens and continue processing instead of signaling an error.
このヘッダーフィールドは拡張可能な構文で定義されており、Preferencesレジストリ（セクション5.1）に含まれる将来の値を許可します。リクエストのPreferヘッダーフィールド内の特定のPreferenceトークンを認識できないか、それに準拠できないサーバーは、それらのトークンを無視して、エラーを通知する代わりに処理を続行する必要があります。
Empty or zero-length values on both the preference token and within parameters are equivalent to no value being specified at all. The following, then, are equivalent examples of a "foo" preference with a single "bar" parameter.
Preferenceトークンとパラメータ内の両方の空または長さゼロの値は、値がまったく指定されていないことと同等です。以下は、単一の「bar」パラメータを持つ「foo」設定の同等な例です。
Prefer: foo; bar
Prefer: foo; bar=""
Prefer: foo=""; bar
An optional set of parameters can be specified for any preference token. The meaning and application of such parameters is dependent on the definition of each preference token and the server's implementation thereof. There is no significance given to the ordering of parameters on any given preference.
任意のPreferenceトークンに対して、オプションのパラメータセットを指定できます。これらのパラメータの意味と適用は、各Preferenceトークンの定義とサーバーの実装に依存します。パラメータの順序に意味はありません。
For both preference token names and parameter names, comparison is case insensitive while values are case sensitive regardless of whether token or quoted-string values are used.
Preferenceトークン名とパラメータ名の両方について、比較は大文字と小文字を区別しませんが、値はトークンと引用符付き文字列のどちらの値が使用されているかに関係なく、大文字と小文字を区別します。
The Prefer header field is end to end and MUST be forwarded by a proxy if the request is forwarded unless Prefer is explicitly identified as being hop by hop using the Connection header field defined by [RFC7230], Section 6.1.
Preferが[RFC7230]セクション6.1で定義されたConnectionヘッダーフィールドを使用して明示的にホップバイホップ（hop-by-hop）であると識別されない限り、リクエストが転送される場合、Preferヘッダーフィールドはエンドツーエンドであり、プロキシによって転送される必要があります。
In various situations, a proxy might determine that it is capable of honoring a preference independently of the server to which the request has been directed. For instance, an intervening proxy might be capable of providing asynchronous handling of a request using 202 (Accepted) responses independently of the origin server. Such proxies can choose to honor the "respond-async" preference on their own regardless of whether or not the origin is capable or willing to do so.
さまざまな状況で、プロキシは、リクエストの送信先サーバーとは無関係に、設定を優先できると判断する場合があります。たとえば、介在するプロキシは、オリジンサーバーとは無関係に、202 (Accepted) レスポンスを使用してリクエストの非同期処理を提供できる場合があります。そのようなプロキシは、オリジンがそれを実行できるかどうかにかかわらず、独自に「respond-async」設定を優先することを選択できます。
Individual preference tokens MAY define their own requirements and restrictions as to whether and how intermediaries can apply the preference to a request independently of the origin server.
個々のPreferenceトークンは、仲介者がオリジンサーバーとは独立してリクエストに設定を適用できるかどうか、またどのように適用するかについて、独自の要件と制限を定義できます。
A client MAY use multiple instances of the Prefer header field in a single message, or it MAY use a single Prefer header field with multiple comma-separated preference tokens. If multiple Prefer header fields are used, it is equivalent to a single Prefer header field with the comma-separated concatenation of all of the tokens. For example, the following are equivalent:
クライアントは、単一のメッセージでPreferヘッダーフィールドの複数のインスタンスを使用することも、複数のコンマ区切りのPreferenceトークンを持つ単一のPreferヘッダーフィールドを使用することもできます。複数のPreferヘッダーフィールドが使用されている場合、それはすべてのトークンをコンマで区切って連結した単一のPreferヘッダーフィールドと同等です。たとえば、以下は同等です。
Multiple Prefer header fields defining three distinct preference tokens:
3つの異なるPreferenceトークンを定義する複数のPreferヘッダーフィールド：
POST /foo HTTP/1.1
Host: example.org
Prefer: respond-async, wait=100
Prefer: handling=lenient
Date: Tue, 20 Dec 2011 12:34:56 GMT
A single Prefer header field defining the same three preference tokens:
同じ3つのPreferenceトークンを定義する単一のPreferヘッダーフィールド：
POST /foo HTTP/1.1
Host: example.org
Prefer: handling=lenient, wait=100, respond-async
Date: Tue, 20 Dec 2011 12:34:56 GMT
To avoid any possible ambiguity, individual preference tokens SHOULD NOT appear multiple times within a single request. If any preference is specified more than once, only the first instance is to be considered. All subsequent occurrences SHOULD be ignored without signaling an error or otherwise altering the processing of the request. This is the only case in which the ordering of preferences within a request is considered to be significant.
起こりうる曖昧さを避けるために、個々のPreferenceトークンは単一のリクエスト内で複数回出現すべきではありません（SHOULD NOT）。いずれかの設定が複数回指定されている場合、最初のインスタンスのみが考慮されます。それ以降のすべての出現は、エラーを通知したりリクエストの処理を変更したりすることなく、無視されるべきです（SHOULD）。これは、リクエスト内の設定の順序が重要であると見なされる唯一のケースです。
Due to the inherent complexities involved with properly implementing server-driven content negotiation, effective caching, and the application of optional preferences, implementers are urged to exercise caution when using preferences in a way that impacts the caching of a response and SHOULD NOT use the Prefer header mechanism for content negotiation. If a server supports the optional application of a preference that might result in a variance to a cache's handling of a response entity, a Vary header field MUST be included in the response listing the Prefer header field regardless of whether the client actually used Prefer in the request. Alternatively, the server MAY include a Vary header with the special value "*" as defined by [RFC7231], Section 8.2.1. Note, however, that use of the "Vary: *" header will make it impossible for a proxy to cache the response.
サーバー主導のコンテンツネゴシエーション、効果的なキャッシング、およびオプションの設定の適用を適切に実装することに伴う固有の複雑さのため、実装者は、レスポンスのキャッシングに影響を与えるような方法で設定を使用する場合には注意が必要であり、コンテンツネゴシエーションのためにPreferヘッダーの仕組みを使用すべきではありません（SHOULD NOT）。サーバーが、キャッシュによるレスポンスエンティティの処理に差異が生じる可能性のある設定のオプション適用をサポートしている場合、クライアントが実際にリクエストでPreferを使用したかどうかにかかわらず、レスポンスにPreferヘッダーフィールドをリストしたVaryヘッダーフィールドを含める必要があります（MUST）。あるいは、サーバーは[RFC7231]セクション8.2.1で定義されている特別な値「*」を持つVaryヘッダーを含めることができます（MAY）。ただし、「Vary: *」ヘッダーを使用すると、プロキシがレスポンスをキャッシュできなくなることに注意してください。
Note that while Preference tokens are similar in structure to HTTP Expect tokens, the Prefer and Expect header fields serve very distinct purposes and preferences cannot be used as expectations.
Preferenceトークンは構造においてHTTP Expectトークンと似ていますが、PreferヘッダーフィールドとExpectヘッダーフィールドは非常に異なる目的で使用され、PreferenceをExpect（期待内容）として使用することはできないことに注意してください。
The following examples illustrate the use of various preferences defined by this specification, as well as undefined extensions for strictly illustrative purposes:
次の例は、この仕様で定義されているさまざまな設定の使用法と、説明目的の未定義の拡張機能を示しています。
1. Return a 202 (Accepted) response for asynchronous processing if the request cannot be processed within 10 seconds. An undefined "priority" preference is also specified:
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. Use lenient processing:
2. 寛大な処理を使用する：
POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: Lenient
{...}
3. Use of an optional, undefined parameter on the return=minimal preference:
3. return=minimal設定でのオプションの未定義パラメータの使用：
POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal; foo="some parameter"
{...}
The Preference-Applied response header MAY be included within a response message as an indication as to which Prefer tokens were honored by the server and applied to the processing of a request.
Preference-Appliedレスポンスヘッダーは、どのPreferenceトークンがサーバーによって尊重され、リクエストの処理に適用されたかを示すものとして、レスポンスメッセージ内に含めることができます。
ABNF:
ABNF：
Preference-Applied = "Preference-Applied" ":" 1#applied-pref
applied-pref = token [ BWS "=" BWS word ]
The syntax of the Preference-Applied header differs from that of the Prefer header in that parameters are not included.
Preference-Appliedヘッダーの構文は、パラメータが含まれていないという点でPreferヘッダーの構文と異なります。
Use of the Preference-Applied header is only necessary when it is not readily and obviously apparent that a server applied a given preference and such ambiguity might have an impact on the client's handling of the response. For instance, when using either the "return=representation" or "return=minimal" preferences, a client application might not be capable of reliably determining if the preference was (or was not) applied simply by examining the payload of the response. In such a case, the Preference-Applied header field can be used.
Preference-Appliedヘッダーの使用が必要になるのは、サーバーが特定の設定を適用したことがすぐに明らかではなく、そのような曖昧さがクライアントのレスポンス処理に影響を与える可能性がある場合だけです。たとえば、「return=representation」または「return=minimal」設定のいずれかを使用する場合、クライアントアプリケーションは、レスポンスのペイロードを調べるだけでは、設定が適用されたか（あるいは適用されなかったか）を確実に判断できない場合があります。そのような場合に、Preference-Appliedヘッダーフィールドを使用できます。
Request:
リクエスト：
PATCH /my-document HTTP/1.1
Host: example.org
Content-Type: application/example-patch
Prefer: return=representation
[{"op": "add", "path": "/a", "value": 1}]
Response:
レスポンス：
HTTP/1.1 200 OK
Content-Type: application/json
Preference-Applied: return=representation
Content-Location: /my-document
{"a": 1}
The following subsections define an initial set of preferences. Additional preferences can be registered for convenience and/or to promote reuse by other applications. This specification establishes an IANA registry of preferences (see Section 5.1).
次のサブセクションでは、初期のPreferenceセットを定義します。便宜上、あるいは他のアプリケーションによる再利用を促進するために、追加の設定を登録できます。この仕様は、PreferenceのIANAレジストリを確立します（セクション5.1を参照）。
The "respond-async" preference indicates that the client prefers the server to respond asynchronously to a response. For instance, in the case when the length of time it takes to generate a response will exceed some arbitrary threshold established by the server, the server can honor the "respond-async" preference by returning a 202 (Accepted) response.
「respond-async」設定は、クライアントがリクエストに対して非同期にレスポンスを返すことを好むことを示します。たとえば、レスポンスの生成にかかる時間がサーバーによって設定された任意のしきい値を超える場合、サーバーは202 (Accepted) レスポンスを返すことで「respond-async」設定を優先できます。
ABNF:
ABNF：
respond-async = "respond-async"
The key motivation for the "respond-async" preference is to facilitate the operation of asynchronous request handling by allowing the client to indicate to a server its capability and preference for handling asynchronous responses.
「respond-async」設定の主な動機は、クライアントが非同期レスポンスを処理するための機能と好みをサーバーに示すことを可能にすることにより、非同期リクエスト処理の操作を容易にすることです。
An example request specifying the "respond-async" preference:
「respond-async」設定を指定するリクエストの例：
POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async
{Data}
{データ}
An example asynchronous response using 202 (Accepted):
202 (Accepted) を使用した非同期レスポンスの例：
HTTP/1.1 202 Accepted
Location: http://example.org/collection/123
While the 202 (Accepted) response status is defined by [RFC7231], little guidance is given on how and when to use the response code and the process for determining the subsequent final result of the operation is left entirely undefined. Therefore, whether and how any given server supports asynchronous responses is an implementation-specific detail that is considered to be out of the scope of this specification.
202 (Accepted) レスポンスステータスは[RFC7231]で定義されていますが、レスポンスコードをいつどのように使用するかについてのガイダンスはほとんどなく、操作の後続の最終結果を決定するプロセスは完全に未定義のままです。したがって、特定のサーバーが非同期レスポンスをサポートするかどうか、またどのようにサポートするかは、この仕様の範囲外と見なされる実装固有の詳細です。
The "return=representation" preference indicates that the client prefers that the server include an entity representing the current state of the resource in the response to a successful request.
「return=representation」設定は、クライアントがサーバーに対して、リクエストの成功に対するレスポンスにリソースの現在の状態を表すエンティティを含めることを好むことを示します。
The "return=minimal" preference, on the other hand, indicates that the client wishes the server to return only a minimal response to a successful request. Typically, such responses would utilize the 204 (No Content) status, but other codes MAY be used as appropriate, such as a 200 (OK) status with a zero-length response entity. The determination of what constitutes an appropriate minimal response is solely at the discretion of the server.
一方、「return=minimal」設定は、クライアントがサーバーに対して、リクエストの成功に対して最小限のレスポンスのみを返すことを望んでいることを示します。通常、そのようなレスポンスは204 (No Content) ステータスを利用しますが、長さゼロのレスポンスエンティティを持つ200 (OK) ステータスなど、他のコードが適切に使用される場合もあります（MAY）。何をもって適切な最小レスポンスとするかの決定は、もっぱらサーバーの裁量に委ねられます。
ABNF:
ABNF：
return = "return" BWS "=" BWS ("representation" / "minimal")
When honoring the "return=representation" preference, the returned representation might not be a representation of the effective request URI when the request is affecting another resource. In such cases, the Content-Location header can be used to identify the URI of the returned representation.
「return=representation」設定を尊重する場合、リクエストが別のリソースに影響を与えているとき、返される表現は有効なリクエストURIの表現ではない可能性があります。そのような場合、Content-Locationヘッダーを使用して、返された表現のURIを識別できます。
The "return=representation" preference is intended to provide a means of optimizing communication between the client and server by eliminating the need for a subsequent GET request to retrieve the current representation of the resource following a modification.
「return=representation」設定は、変更後にリソースの現在の表現を取得するための後続のGETリクエストを不要にすることで、クライアントとサーバー間の通信を最適化する手段を提供することを目的としていています。
After successfully processing a modification request such as a POST or PUT, a server can choose to return either an entity describing the status of the operation or a representation of the modified resource itself. While the selection of which type of entity to return, if any at all, is solely at the discretion of the server, the "return=representation" preference -- along with the "return=minimal" preference defined below -- allow the server to take the client's preferences into consideration while constructing the response.
POSTやPUTなどの変更リクエストを正常に処理した後、サーバーは、操作のステータスを説明するエンティティ、または変更されたリソース自体の表現のいずれかを返すことを選択できます。どのタイプのエンティティを返すか（あるいは全く返さないか）の選択はもっぱらサーバーの裁量ですが、「return=representation」設定は、以下で定義する「return=minimal」設定とともに、サーバーがレスポンスを構築する際にクライアントの好みを考慮に入れることを可能にします。
An example request specifying the "return=representation" preference:
「return=representation」設定を指定するリクエストの例：
PATCH /item/123 HTTP/1.1
Host: example.org
Content-Type: application/example-patch
Prefer: return=representation
1c1
< ABCDEFGHIJKLMNOPQRSTUVWXYZ
---
> BCDFGHJKLMNPQRSTVWXYZ
An example response containing the resource representation:
リソース表現を含むレスポンスの例：
HTTP/1.1 200 OK
Content-Location: http://example.org/item/123
Content-Type: text/plain
ETag: "d3b07384d113edec49eaa6238ad5ff00"
BCDFGHJKLMNPQRSTVWXYZ
BCDFGHJKLMNPQRSTVWXYZ
In contrast, the "return=minimal" preference can reduce the amount of data the server is required to return to the client following a request. This can be particularly useful, for instance, when communicating with limited-bandwidth mobile devices or when the client simply does not require any further information about the result of a request beyond knowing if it was successfully processed.
対照的に、「return=minimal」設定は、リクエストの後にサーバーがクライアントに返す必要のあるデータ量を削減できます。これは、たとえば、帯域幅が制限されたモバイルデバイスと通信する場合や、クライアントが単にリクエストが正常に処理されたかどうかを知る以外に、リクエスト結果に関する追加情報を必要としない場合に特に役立ちます。
An example request specifying the "return=minimal" preference:
「return=minimal」設定を指定するリクエストの例：
POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal
{Data}
{データ}
An example minimal response:
最小レスポンスの例：
HTTP/1.1 201 Created
Location: http://example.org/collection/123
The "return=minimal" and "return=representation" preferences are mutually exclusive directives. It is anticipated that there will never be a situation where it will make sense for a single request to include both preferences. Any such requests will likely be the result of a coding error within the client. As such, a request containing both preferences can be treated as though neither were specified.
「return=minimal」と「return=representation」設定は、相互に排他的なディレクティブです。単一のリクエストに両方の設定を含めることが合理的である状況は決して起こらないと予想されます。そのようなリクエストは、おそらくクライアント内のコーディングエラーの結果です。そのため、両方の設定を含むリクエストは、どちらも指定されていないかのように扱うことができます。
The "wait" preference can be used to establish an upper bound on the length of time, in seconds, the client expects it will take the server to process the request once it has been received. In the case that generating a response will take longer than the time specified, the server, or proxy, can choose to utilize an asynchronous processing model by returning -- for example -- a 202 (Accepted) response.
「wait」Preferenceは、クライアントがリクエストを送信してからサーバーが処理を完了するまでにかかると予想する時間の長さの上限を、秒単位で指定するために使用できます。レスポンスの生成に指定された時間よりも長くかかる場合、サーバーまたはプロキシは、たとえば202 (Accepted) レスポンスを返すことによって、非同期処理モデルを利用することを選択できます。
ABNF:
ABNF：
wait = "wait" BWS "=" BWS delta-seconds
It is important to consider that HTTP messages spend some time traversing the network and being processed by intermediaries. This increases the length of time that a client will wait for a response in addition to the time the server takes to process the request. A client that has strict timing requirements can estimate these factors and adjust the wait value accordingly.
HTTPメッセージがネットワークを通過し、仲介者によって処理されるには、ある程度の時間がかかることを考慮することが重要です。これにより、サーバーがリクエストを処理するのにかかる時間に加えて、クライアントがレスポンスを待機する時間が長くなります。厳密なタイミング要件を持つクライアントは、これらの要因を推定し、それに応じてwait値を調整できます。
As with other preferences, the "wait" preference could be ignored. Clients can abandon requests that take longer than they are prepared to wait.
他の設定と同様に、「wait」設定は無視される可能性があります。クライアントは、待機できる時間よりも長くかかるリクエストを破棄できます。
For example, a server receiving the following request might choose to respond asynchronously if processing the request will take longer than 10 seconds:
たとえば、次のリクエストを受信したサーバーは、リクエストの処理に10秒以上かかる場合に、非同期で応答することを選択する可能性があります。
POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10
{Data}
{データ}
4.4. The "handling=strict" and "handling=lenient" Processing Preferences
4.4. "handling=strict" および "handling=lenient" 処理設定
The "handling=strict" and "handling=lenient" preferences indicate, at the server's discretion, how the client wishes the server to handle potential error conditions that can arise in the processing of a request. For instance, if the payload of a request contains various minor syntactical or semantic errors, but the server is still capable of comprehending and successfully processing the request, a decision must be made to either reject the request with an appropriate "4xx" error response or go ahead with processing. The "handling=strict" preference can be used to indicate that, while any particular error may be recoverable, the client would prefer that the server reject the request. The "handling=lenient" preference, on the other hand, indicates that the client wishes the server to attempt to process the request.
「handling=strict」および「handling=lenient」設定は、サーバーの裁量により、リクエストの処理で発生しうる潜在的なエラー条件をサーバーがどのように処理するかについてのクライアントの希望を示します。たとえば、リクエストのペイロードにいくつかの軽微な構文的または意味的なエラーが含まれているものの、サーバーがリクエストを理解して正常に処理できる場合、適切な「4xx」エラーレスポンスでリクエストを拒否するか、処理を続行するかの決定を下す必要があります。「handling=strict」設定は、特定のエラーが回復可能であっても、クライアントはサーバーがリクエストを拒否することを好むことを示すために使用できます。一方、「handling=lenient」設定は、クライアントがサーバーに対してリクエストの処理を試みることを望んでいることを示します。
ABNF:
ABNF：
handling = "handling" BWS "=" BWS ("strict" / "lenient")
An example request specifying the "strict" preference:
「strict」設定を指定するリクエストの例：
POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: handling=strict
The "handling=strict" and "handling=lenient" preferences are mutually exclusive directives. It is anticipated that there will never be a situation where it will make sense for a single request to include both preferences. Any such requests will likely be the result of a coding error within the client. As such, a request containing both preferences can be treated as though neither were specified.
「handling=strict」と「handling=lenient」設定は相互に排他的なディレクティブです。単一のリクエストに両方の設定を含めることが合理的である状況は決して起こらないと予想されます。そのようなリクエストは、おそらくクライアント内のコーディングエラーの結果です。そのため、両方の設定を含むリクエストは、どちらも指定されていないかのように扱うことができます。
The 'Prefer' and 'Preference-Applied' header fields have been added to the "Permanent Message Header Field Names" registry defined in [RFC3864] (http://www.iana.org/assignments/message-headers).
「Prefer」および「Preference-Applied」ヘッダーフィールドが、[RFC3864] (http://www.iana.org/assignments/message-headers) で定義されている「Permanent Message Header Field Names」レジストリに追加されました。
Header field name: Prefer
ヘッダーフィールド名：Prefer
Applicable Protocol: HTTP
該当するプロトコル：HTTP
Status: Standard
ステータス：標準
Author: James M Snell <jasnell@gmail.com>
Change controller: IETF
コントローラの変更：IETF
Specification document: this specification, Section 2
仕様書：この仕様、セクション2
Header field name: Preference-Applied
ヘッダーフィールド名：Preference-Applied
Applicable Protocol: HTTP
該当するプロトコル：HTTP
Status: Standard
ステータス：標準
Author: James M Snell <jasnell@gmail.com>
Change controller: IETF
コントローラの変更：IETF
Specification document: this specification, Section 3
仕様書：この仕様、セクション3
IANA has created a new registry, "HTTP Preferences", under the "Hypertext Transfer Protocol (HTTP) Parameters" registry. New registrations will use the Specification Required policy [RFC5226]. The requirements for registered preferences are described in Section 4.
IANAは、「Hypertext Transfer Protocol (HTTP) Parameters」レジストリの下に「HTTP Preferences」という新しいレジストリを作成しました。新規登録は、「Specification Required（仕様が必要）」ポリシー[RFC5226]を使用します。登録されたPreferenceの要件は、セクション4で説明されています。
Registration requests consist of the completed registration template below, typically published in the required specification. However, to allow for the allocation of values prior to publication, the Designated Expert can approve registration based on a separately submitted template once they are satisfied that a specification will be published. Preferences can be registered by third parties if the Designated Expert determines that an unregistered preference is widely deployed and not likely to be registered in a timely manner.
登録申請は、通常、必要な仕様書で公開される以下の完成した登録テンプレートで構成されます。ただし、公開前に値を割り当てることができるように、指定された専門家 (Designated Expert) は、仕様書が公開されることが確実であると判断した場合、別途提出されたテンプレートに基づいて登録を承認できます。未登録のPreferenceが広く普及しており、適時に登録される見込みがないと指定された専門家が判断した場合、第三者がPreferenceを登録できます。
The registration template is:
登録テンプレートは以下の通りです。
o Preference: (A value for the Prefer request header field that conforms to the syntax rule given in Section 2)
o Preference: (セクション2で指定された構文規則に準拠する、Preferリクエストヘッダーフィールドの値)
o Value: (An enumeration or description of possible values for the preference token).
o Value: (Preferenceトークンの可能な値の列挙または説明)。
o Optional Parameters: (An enumeration of optional parameters, and their values, associated with the preference token).
o Optional Parameters: (Preferenceトークンに関連付けられた、オプションのパラメータとその値の列挙)。
o Description:
o Description (説明):
o Reference:
o Reference (参照):
o Notes: [optional]
o Notes (注記): [オプション]
The "Value" and "Optional Parameters" fields MAY be omitted from the registration template if the specific preference token definition does not define either.
特定のPreferenceトークンの定義でいずれも定義されていない場合、「Value」および「Optional Parameters」フィールドは登録テンプレートから省略できます（MAY）。
Registration requests should be sent to the <ietf-http-wg@w3.org> mailing list, marked clearly in the subject line (e.g., "NEW PREFERENCE - example" to register an "example" preference). Within at most 14 days of the request, the Designated Expert(s) will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful.
登録申請は、件名に明記した上で <ietf-http-wg@w3.org> メーリングリストに送信する必要があります（例：「NEW PREFERENCE - example」として「example」設定を登録するなど）。申請から最大14日以内に、指定された専門家が登録申請を承認または否認し、その決定をレビューリストとIANAに通知します。否認された場合は、その理由の説明と、該当する場合は申請を成功させるための提案が含まれるべきです。
The Expert Reviewer shall ensure:
専門家レビューアは、以下を確認するものとします。
o That the requested preference name conforms to the token rule in Section 2 and that it is not identical to any other registered preference name;
o 申請されたPreference名がセクション2のtokenルールに準拠しており、他の登録済みPreference名と同一ではないこと。
o That any associated value, parameter names, and values conform to the relevant ABNF grammar specifications in Section 2;
o 関連付けられた値、パラメータ名、および値が、セクション2の関連するABNF文法仕様に準拠していること。
o That the name is appropriate to the specificity of the preference; i.e., if the semantics are highly specific to a particular application, the name should reflect that, so that more general names remain available for less specific uses.
o 名前がその設定の具体性に適していること。つまり、セマンティクスが特定のアプリケーションに非常に特化している場合、名前はそれを反映すべきであり、それによって、より一般的な名前をより汎用的な用途に残しておくことができます。
o That requested preferences do not constrain servers, clients, or any intermediaries to any behavior required for successful processing; and
o 申請されたPreferenceが、リクエストの正常な処理に必要な動作をサーバー、クライアント、または仲介者に強制しないこと。および
o That the specification document defining the preference includes a proper and complete discussion of any security considerations relevant to the use of the preference.
o Preferenceを定義する仕様書に、その設定の使用に関連するセキュリティ上の考慮事項についての適切かつ完全な議論が含まれていること。
The "HTTP Preferences" registry's initial contents are:
「HTTP Preferences」レジストリの初期内容は以下の通りです。
o Preference: respond-async
o Preference: respond-async
o Description: Indicates that the client prefers that the server respond asynchronously to a request.
o 説明: クライアントが、サーバーがリクエストに対して非同期で応答することを好むことを示します。
o Reference: [this specification], Section 4.1
o 参照: [本仕様]、セクション4.1
o Preference: return
o Preference: return
o Value: One of either "minimal" or "representation"
o 値: 「minimal」または「representation」のいずれか
o Description: When the value is "minimal", it indicates that the client prefers that the server return a minimal response to a request. When the value is "representation", it indicates that the client prefers that the server include a representation of the current state of the resource in response to a request.
o 説明: 値が「minimal」の場合、クライアントが、サーバーがリクエストに対して最小限のレスポンスを返すことを好むことを示します。値が「representation」の場合、クライアントが、サーバーがリクエストに対してリソースの現在の状態の表現を含めることを好むことを示します。
o Reference: [this specification], Section 4.2
o 参照: [本仕様]、セクション4.2
o Preference: wait
o Preference: wait
o Description: Indicates an upper bound to the length of time the client expects it will take for the server to process the request once it has been received.
o 説明: サーバーがリクエストを受信してから処理を完了するまでにかかるとクライアントが予想する時間の長さの上限を示します。
o Reference: [this specification], Section 4.3
o 参照: [本仕様]、セクション4.3
o Preference: handling
o Preference: handling
o Value: One of either "strict" or "lenient"
o 値: 「strict」または「lenient」のいずれか
o Description: When value is "strict", it indicates that the client wishes the server to apply strict validation and error handling to the processing of a request. When the value is "lenient", it indicates that the client wishes the server to apply lenient validation and error handling to the processing of the request.
o 説明: 値が「strict」の場合、クライアントが、サーバーがリクエストの処理に厳密な検証とエラー処理を適用することを望んでいることを示します。値が「lenient」の場合、クライアントが、サーバーがリクエストの処理に寛大な検証とエラー処理を適用することを望んでいることを示します。
o Reference: [this specification], Section 4.4
o 参照: [本仕様]、セクション4.4
Specific preferences requested by a client can introduce security considerations and concerns beyond those discussed within HTTP/1.1 [RFC7230] and its associated specification documents (see [RFC7230] for the list of associated works). Implementers need to refer to the specifications and descriptions of each preference to determine the security considerations relevant to each.
クライアントが要求する特定のPreferenceは、HTTP/1.1 [RFC7230] およびその関連仕様書で議論されているものを超えて、セキュリティ上の考慮事項や懸念事項をもたらす可能性があります（関連する著作のリストについては [RFC7230] を参照）。実装者は、各Preferenceの仕様と説明を参照して、それぞれに関連するセキュリティ上の考慮事項を判断する必要があります。
A server could incur greater costs in attempting to comply with a particular preference (for instance, the cost of providing a representation in a response that would not ordinarily contain one; or the commitment of resources necessary to track state for an asynchronous response). Unconditional compliance from a server could allow the use of preferences for denial of service. A server can ignore an expressed preference to avoid expending resources that it does not wish to commit.
サーバーは、特定のPreferenceに従おうとすることで、より大きなコストが発生する可能性があります（たとえば、通常は含まれないレスポンスで表現を提供するコスト、または非同期レスポンスの状態を追跡するために必要なリソースの投入）。サーバーが無条件にPreferenceを遵守すると、サービス拒否攻撃（DoS）にPreferenceが悪用される可能性があります。サーバーは、投入したくないリソースの消費を避けるために、表明されたPreferenceを無視することができます。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, 1997年3月。
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, September 2004.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, 2004年9月。
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2008年5月。
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, 2008年1月。
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2014.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, 2014年6月。
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2014年6月。
[RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing Protocol", RFC 5023, October 2007.
[RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing Protocol", RFC 5023, 2007年10月。
Author's Address
著者のアドレス
James M Snell
James M Snell
EMail: jasnell@gmail.com