RFC 10008 - The HTTP QUERY Method 日本語訳

原文URL : https://www.rfc-editor.org/rfc/rfc10008.html
タイトル : RFC 10008 - HTTP QUERY メソッド
翻訳編集 : 自動生成

[要約] RFC 10008は、リクエスト内容を安全かつ冪等に処理して結果を返すHTTP QUERYメソッドを規定します。本文を伴う検索などPOSTに似た処理を、部分的な状態変更を懸念せず自動再試行・再開できるようにし、Accept-Queryフィールド、コンテンツネゴシエーション、キャッシュ、条件付き・範囲要求などの扱いを定義します。

Internet Engineering Task Force (IETF)                        J. Reschke
Request for Comments: 10008                                   greenbytes
Category: Standards Track                                     J.M. Snell
ISSN: 2070-1721                                               Cloudflare
                                                               M. Bishop
                                                                  Akamai
                                                               June 2026

The HTTP QUERY Method

HTTP QUERY メソッド

Abstract

概要

This specification defines the QUERY method for HTTP. A QUERY requests that the request target process the enclosed content in a safe and idempotent manner and then respond with the result of that processing. This is similar to POST requests, but QUERY requests can be automatically repeated or restarted without concern for partial state changes.

この仕様は、HTTP の QUERY メソッドを定義します。QUERY は、リクエストのターゲットが、囲まれたコンテンツを安全かつ冪等な方法で処理し、その処理の結果で応答することを要求します。これは POST リクエストに似ていますが、QUERY リクエストは部分的な状態の変更を気にせずに自動的に繰り返したり再開したりできます。

Status of This Memo

本文書の状態

This is an Internet Standards Track document.

これはインターネット標準化トラックの文書です。

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 7841.

このドキュメントは Internet Engineering Task Force (IETF) の成果物です。これは IETF コミュニティのコンセンサスを表しています。この文書は公開レビューを受け、Internet Engineering Steering Group (IESG) によって公開が承認されています。インターネット標準の詳細については、RFC 7841 のセクション 2 を参照してください。

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc10008.

この文書の現在のステータス、正誤表、およびそれに対するフィードバックの提供方法に関する情報は、https://www.rfc-editor.org/info/rfc10008 で入手できます。

Copyright Notice

著作権表示

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.

この文書は、BCP 78 およびこの文書の発行日に有効な IETF 文書に関する IETF トラストの法的規定 (https://trustee.ietf.org/license-info) の対象となります。これらの文書には、この文書に関するお客様の権利と制限が記載されているため、注意深くお読みください。この文書から抽出されたコードコンポーネントには、トラスト法的規定のセクション 4.e に記載されている改訂 BSD ライセンステキストが含まれている必要があり、改訂 BSD ライセンスに記載されているように保証なしで提供されます。

   1.  Introduction
     1.1.  Terminology
     1.2.  Notational Conventions
   2.  QUERY Method
     2.1.  Media Types and Content Negotiation
     2.2.  Equivalent Resource
     2.3.  Content-Location Response Field
     2.4.  Location Response Field
     2.5.  Redirection
     2.6.  Conditional Requests
     2.7.  Caching
     2.8.  Range Requests
   3.  The Accept-Query Header Field
   4.  Security Considerations
   5.  IANA Considerations
     5.1.  Registration of the QUERY Method
     5.2.  Registration of the Accept-Query Field
   6.  References
     6.1.  Normative References
     6.2.  Informative References
   Appendix A.  Examples
     A.1.  Simple Query
     A.2.  Discovery of QUERY Support
     A.3.  Discovery of QUERY Formats
     A.4.  Content-Location, Location, and Indirect Responses
       A.4.1.  Using Content-Location
       A.4.2.  Using Location
       A.4.3.  Indirect Responses
     A.5.  Conditional Requests
     A.6.  More Query Formats
   Appendix B.  Selection of the Method Name 'QUERY'
   Acknowledgements
   Contributors
   Authors' Addresses

1. Introduction

1. はじめに

This specification defines the HTTP QUERY request method as a means of making a safe, idempotent request (Section 9.2 of [HTTP]) that encloses a representation describing how the request is to be processed by the target resource.

この仕様は、ターゲットリソースによってリクエストがどのように処理されるかを記述する表現を囲む、安全でべき等なリクエスト ([HTTP] のセクション 9.2) を作成する手段として HTTP QUERY リクエストメソッドを定義します。

A common query pattern is:

一般的なクエリパターンは次のとおりです。

   GET /feed?q=foo&limit=10&sort=-published HTTP/1.1
   Host: example.org

However, when the data conveyed is too voluminous to be encoded in the request's URI, this pattern becomes problematic:

ただし、送信されるデータがリクエストの URI でエンコードするには大きすぎる場合、このパターンは問題になります。

* size limits often are not known ahead of time because a request can pass through many uncoordinated systems (but note that Section 4.1 of [HTTP] recommends senders and recipients to support at least 8000 octets),

* リクエストは多くの調整されていないシステムを通過する可能性があるため、サイズ制限は事前に分からないことがよくあります (ただし、[HTTP] のセクション 4.1 では、送信者と受信者が少なくとも 8000 オクテットをサポートすることが推奨されていることに注意してください)。

* expressing certain kinds of data in the target URI is inefficient because of the overhead of encoding that data into a valid URI,

* ターゲット URI で特定の種類のデータを表現することは、そのデータを有効な URI にエンコードするオーバーヘッドのため非効率的です。

* request URIs are more likely to be logged than request content and may also turn up in bookmarks,

* リクエスト URI はリクエストコンテンツよりもログに記録される可能性が高く、ブックマークにも表示される可能性があります。

* encoding queries directly into the request URI effectively casts every possible combination of query inputs as distinct resources.

* クエリをリクエスト URI に直接エンコードすると、クエリ入力のあらゆる可能な組み合わせが個別のリソースとして効果的にキャストされます。

As an alternative to using GET, many implementations make use of the HTTP POST method to perform queries, as illustrated in the example below. In this case, the input to the query operation is passed as the request content as opposed to using the request URI's query component.

以下の例に示すように、多くの実装では、GET を使用する代わりに、HTTP POST メソッドを使用してクエリを実行します。この場合、クエリ操作への入力は、リクエスト URI のクエリコンポーネントを使用するのではなく、リクエストコンテンツとして渡されます。

A typical use of HTTP POST for requesting a query is:

クエリをリクエストするための HTTP POST の一般的な使用法は次のとおりです。

   POST /feed HTTP/1.1
   Host: example.org
   Content-Type: application/x-www-form-urlencoded

   q=foo&limit=10&sort=-published

In this variation, however, it is not readily apparent -- without specific knowledge of the resource and server to which the request is being sent -- that a safe, idempotent query is being performed.

ただし、この変形例では、リクエストの送信先となるリソースとサーバーに関する具体的な知識がなければ、安全で冪等のクエリが実行されているかどうかはすぐにはわかりません。

The QUERY method provides a solution that spans the gap between the use of GET and POST, with the example above being expressed as:

QUERY メソッドは、GET と POST の使用の間のギャップを埋めるソリューションを提供します。上記の例は次のように表されます。

   QUERY /feed HTTP/1.1
   Host: example.org
   Content-Type: application/x-www-form-urlencoded

   q=foo&limit=10&sort=-published

As with POST, the input to the query operation is passed as the content of the request rather than as part of the request URI. Unlike POST, however, the method is explicitly safe and idempotent, allowing functions like caching and automatic retries to operate.

POST と同様に、クエリ操作への入力は、リクエスト URI の一部としてではなく、リクエストのコンテンツとして渡されます。ただし、POST とは異なり、このメソッドは明示的に安全かつ冪等であるため、キャッシュや自動再試行などの機能を実行できます。

Recognizing the design principle that any important resource ought to be identified by a URI, this specification describes how a server can assign URIs to both the query itself or to a specific query result, for later use in a GET request.

重要なリソースは URI によって識別されるべきであるという設計原則を認識し、この仕様では、後で GET リクエストで使用するために、サーバーがクエリ自体または特定のクエリ結果の両方に URI を割り当てる方法について説明します。

Summarizing:

要約:

   +==========+=================+=================+===================+
   |          |GET              |QUERY            | POST              |
   +==========+=================+=================+===================+
   |Safe      |yes              |yes              | potentially no    |
   +----------+-----------------+-----------------+-------------------+
   |Idempotent|yes              |yes              | potentially no    |
   +----------+-----------------+-----------------+-------------------+
   |URI for   |yes (by          |optional         | no                |
   |query     |definition)      |(Location        |                   |
   |itself    |                 |response field)  |                   |
   +----------+-----------------+-----------------+-------------------+
   |URI for   |optional         |optional         | optional          |
   |query     |(Content-Location|(Content-Location| (Content-Location |
   |result    |response field)  |response field)  | response field)   |
   +----------+-----------------+-----------------+-------------------+
   |Cacheable |yes              |yes              | yes, but only for |
   |          |                 |                 | future GET or     |
   |          |                 |                 | HEAD requests     |
   +----------+-----------------+-----------------+-------------------+
   |Content   |"no defined      |expected         | expected          |
   |(body)    |semantics"       |(semantics per   | (semantics per    |
   |          |                 |target resource) | target resource)  |
   +----------+-----------------+-----------------+-------------------+

Table 1: Summary of Relevant Method Properties

表 1: 関連するメソッドのプロパティの概要

1.1. Terminology

1.1. 用語

This document uses terminology defined in Section 3 of [HTTP].

この文書では、[HTTP] のセクション 3 で定義されている用語を使用します。

Furthermore, it uses the terms _URI query parameter_ for parameters in the query component of a URI (Section 4.2.2 of [HTTP]) and _query content_ for the request content (Section 6.4 of [HTTP]) of a QUERY request.

さらに、URI のクエリコンポーネント内のパラメータ ([HTTP] のセクション 4.2.2) には _URI クエリパラメータ_ という用語が使用され、QUERY リクエストのリクエストコンテンツ ([HTTP] のセクション 6.4) には _クエリコンテンツ_ という用語が使用されます。

1.2. Notational Conventions

1.2. 表記規則

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

このドキュメント内のキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「NOT RECOMMENDED」、「MAY」、および「OPTIONAL」は、ここに示すようにすべて大文字で表示されている場合にのみ、BCP 14 [RFC2119] [RFC8174] で説明されているように解釈されます。

2. QUERY Method

2. QUERYメソッド

The QUERY method is used to initiate a server-side query. Unlike the GET method, which requests a representation of the resource identified by the target URI (as defined by Section 7.1 of [HTTP]), the QUERY method is used to ask the target resource to perform a query operation within the scope of that target resource.

QUERY メソッドは、サーバー側のクエリを開始するために使用されます。([HTTP] のセクション 7.1 で定義されている) ターゲット URI によって識別されるリソースの表現を要求する GET メソッドとは異なり、QUERY メソッドは、ターゲットリソースのスコープ内でクエリ操作を実行するようにターゲットリソースに要求するために使用されます。

The content of the request and its media type define the query. The origin server determines the scope of the operation based on the target resource.

リクエストの内容とそのメディアタイプによってクエリが定義されます。オリジンサーバーは、ターゲットリソースに基づいて操作の範囲を決定します。

Servers MUST fail the request if the Content-Type request field ([HTTP], Section 8.3) is missing or is inconsistent with the request content.

Content-Type リクエストフィールド ([HTTP]、セクション 8.3) が欠落している場合、またはリクエストの内容と一致しない場合、サーバーはリクエストを失敗しなければなりません (MUST)。

As for all HTTP methods, the target URI's query part takes part in identifying the resource being queried. Whether and how it directly affects the result of the query is specific to the resource and is out of scope for this specification.

すべての HTTP メソッドと同様、ターゲット URI のクエリ部分は、クエリ対象のリソースの識別に関与します。それがクエリの結果に直接影響するかどうか、またどのように影響するかはリソースに固有であり、この仕様の範囲外です。

QUERY requests are safe with regard to the target resource ([HTTP], Section 9.2.1); that is, the client does not request or expect any change to the state of the target resource. This does not prevent the server from creating additional HTTP resources through which additional information can be retrieved (see Sections 2.3 and 2.4).

QUERY リクエストは、ターゲットリソースに関しては安全です ([HTTP]、セクション 9.2.1)。つまり、クライアントはターゲットリソースの状態の変更を要求したり、変更を期待したりしません。これは、サーバーが追加情報を取得できる追加の HTTP リソースを作成することを妨げるものではありません (セクション 2.3 および 2.4 を参照)。

Furthermore, QUERY requests are idempotent ([HTTP], Section 9.2.2); they can be retried or repeated when needed, for instance, after a connection failure.

さらに、QUERY リクエストはべき等です ([HTTP]、セクション 9.2.2)。接続失敗後など、必要に応じて再試行または繰り返すことができます。

As per Section 15.3 of [HTTP], a 2xx (Successful) response code signals that the request was successfully received, understood, and accepted.

[HTTP] のセクション 15.3 に従って、2xx (成功) 応答コードは、リクエストが正常に受信、理解、受け入れられたことを示します。

In particular, a 200 (OK) response indicates that the query was successfully processed and the results of that processing are enclosed as the response content.

特に、200 (OK) 応答は、クエリが正常に処理されたことを示し、その処理の結果が応答コンテンツとして含まれます。

2.1. Media Types and Content Negotiation

2.1. メディアタイプとコンテンツネゴシエーション

The semantics of a QUERY request depend both on the request content and the associated metadata, such as the media type ([HTTP], Section 8.3.1). In general, any problem with requests where content and metadata are inconsistent MUST be rejected with a 4xx (Client Error) response ([HTTP], Section 15.5).

QUERY リクエストのセマンティクスは、リクエストの内容と、メディアタイプ ([HTTP]、セクション 8.3.1) などの関連するメタデータの両方に依存します。一般に、コンテンツとメタデータが矛盾するリクエストに関する問題は、4xx (クライアントエラー) 応答で拒否されなければなりません ([HTTP]、セクション 15.5)。

The list below describes various cases of failures and recommends specific status codes:

以下のリストでは、障害のさまざまなケースについて説明し、特定のステータスコードを推奨します。

* If a request lacks media type information, it is incorrect by definition and needs to fail with a 4xx status code such as 400 (Client Error).

* リクエストにメディアタイプ情報が欠如している場合、そのリクエストは定義上正しくないため、400 (クライアントエラー) などの 4xx ステータスコードで失敗する必要があります。

* If a media type is specified but is not supported by the resource, a 415 (Unsupported Media Type) is appropriate. This specifically includes the case where the media type is known in principle, but it lacks semantics specific to a QUERY to the target resource. In both cases, the Accept-Query response field (Section 3) can be used to inform the client of the media types that are supported.

* メディアタイプが指定されているがリソースでサポートされていない場合は、415 (サポートされていないメディアタイプ) が適切です。これには、原則としてメディアタイプがわかっているが、ターゲットリソースへのクエリに固有のセマンティクスが欠けている場合が特に含まれます。どちらの場合も、Accept-Query 応答フィールド (セクション 3) を使用して、サポートされているメディアタイプをクライアントに通知できます。

* If a media type is specified but is inconsistent with the actual request content, a 400 (Bad Request) can be returned. That is, a server is not allowed to infer a media type from the request content and then override a missing or "erroneous" value (i.e., "content sniffing").

* メディアタイプが指定されていても、実際のリクエストの内容と一致しない場合、400 (Bad Request) が返されることがあります。つまり、サーバーはリクエストのコンテンツからメディアタイプを推測し、欠落している値または「誤った」値をオーバーライドすること (つまり、「コンテンツスニッフィング」) を行うことはできません。

* If the media type is specified and understood, and the content is indeed consistent with the type, but the query cannot be processed due to the actual contents of the query, the status 422 (Unprocessable Content) can be used. An example would be a syntactically correct SQL query that identifies a non-existent table.

* メディアタイプが指定および理解されており、コンテンツが確かにそのタイプと一致しているが、クエリの実際のコンテンツが原因でクエリを処理できない場合は、ステータス 422 (処理できないコンテンツ) を使用できます。例としては、存在しないテーブルを識別する構文的に正しい SQL クエリが挙げられます。

* If the client requests a specific response media type using the Accept field ([HTTP], Section 12.5.1) that is not supported by the resource, a status code of 406 (Not Acceptable) is appropriate.

* クライアントが、リソースでサポートされていない Accept フィールド ([HTTP]、セクション 12.5.1) を使用して特定の応答メディアタイプを要求した場合、ステータスコード 406 (Not Acceptable) が適切です。

2.2. Equivalent Resource

2.2. 同等のリソース

The _equivalent resource_ for any given QUERY request is a resource that responds to GET requests, represents that QUERY request and its target, and takes both message content and metadata into account (Section 6 of [HTTP]). In particular, this includes representation metadata (Section 8 of [HTTP]) such as the content's media type.

特定の QUERY リクエストの「同等のリソース」は、GET リクエストに応答し、その QUERY リクエストとそのターゲットを表し、メッセージの内容とメタデータの両方を考慮するリソースです ([HTTP] のセクション 6)。特に、これには、コンテンツのメディアタイプなどの表現メタデータ ([HTTP] のセクション 8) が含まれます。

In other words, the equivalent resource is derived from the resource implementing QUERY by incorporating the request content.

言い換えれば、同等のリソースは、リクエストの内容を組み込むことによって QUERY を実装するリソースから派生します。

The term _equivalent resource_ is used as a means to define behavior for other HTTP aspects, such as selected representations. Servers can but do not have to assign URIs to these resources (see Section 1.1 of [URI]). If they do so, these resources will become accessible for GET requests.

「同等のリソース」という用語は、選択された表現など、他の HTTP 側面の動作を定義する手段として使用されます。サーバーはこれらのリソースに URI を割り当てることができますが、割り当てる必要はありません ([URI] のセクション 1.1 を参照)。そうすると、これらのリソースは GET リクエストでアクセスできるようになります。

2.3. Content-Location Response Field

2.3. コンテンツと場所の応答フィールド

A successful response (2xx, Section 15.3 of [HTTP]) can include a Content-Location header field containing an identifier for a resource corresponding to the results of the operation; see Section 8.7 of [HTTP] for details. This represents a claim from the server that a client can send a GET request for the indicated URI to retrieve the results of the query operation just performed. The indicated resource might be temporary.

成功した応答 (2xx、[HTTP] のセクション 15.3) には、操作の結果に対応するリソースの識別子を含む Content-Location ヘッダーフィールドを含めることができます。詳細については、[HTTP] のセクション 8.7 を参照してください。これは、クライアントが指定された URI に GET リクエストを送信して、実行されたクエリ操作の結果を取得できるというサーバーからの要求を表します。示されたリソースは一時的なものである可能性があります。

See Appendix A.4.1 for an example.

例については、付録 A.4.1 を参照してください。

2.4. Location Response Field

2.4. 位置応答フィールド

A server can assign a URI to the equivalent resource (Section 2.2) of a QUERY request. If the server does so, the URI of that resource can be included in the Location header field of the 2xx response (see Section 10.2.2 of [HTTP]). This represents a claim that a client can send a GET request to the indicated URI to repeat the query operation just performed without resending the query content. This resource's URI might be temporary; if a future request fails, the client can retry using the original QUERY request target and the previously submitted content.

サーバーは、QUERY リクエストの同等のリソース (セクション 2.2) に URI を割り当てることができます。サーバーがそうする場合、そのリソースの URI を 2xx 応答の Location ヘッダーフィールドに含めることができます ([HTTP] のセクション 10.2.2 を参照)。これは、クライアントが指定された URI に GET リクエストを送信して、クエリコンテンツを再送信せずに実行したばかりのクエリ操作を繰り返すことができるという主張を表します。このリソースの URI は一時的なものである可能性があります。今後のリクエストが失敗した場合、クライアントは元の QUERY リクエストターゲットと以前に送信されたコンテンツを使用して再試行できます。

See Appendix A.4.2 for an example.

例については、付録 A.4.2 を参照してください。

2.5. Redirection

2.5. リダイレクション

In some cases, the server may choose to respond indirectly to the QUERY request by redirecting the user agent to a different URI (see Section 15.4 of [HTTP]).

場合によっては、サーバーは、ユーザーエージェントを別の URI にリダイレクトすることで、QUERY リクエストに間接的に応答することを選択することがあります ([HTTP] のセクション 15.4 を参照)。

A response with either status codes 301 (Moved Permanently, [HTTP], Section 15.4.2) or 308 (Permanent Redirect, [HTTP], Section 15.4.9) indicates that the target resource has permanently moved to a different URI referenced by the Location response field ([HTTP], Section 10.2.2). Likewise, a response with either status codes 302 (Found, [HTTP], Section 15.4.3) or 307 (Temporary Redirect, [HTTP], Section 15.4.8) indicates that the target resource has temporarily moved. In all four cases, the server is suggesting that the user agent can accomplish its original QUERY request by sending a similar QUERY request to the new target URI referenced by the Location.

ステータスコード 301 (Moved Permanently、[HTTP]、セクション 15.4.2) または 308 (Permanent Redirect、[HTTP]、セクション 15.4.9) のいずれかの応答は、ターゲットリソースが Location 応答フィールド ([HTTP]、セクション 10.2.2) によって参照される別の URI に永続的に移動したことを示します。同様に、ステータスコード 302 (Found、[HTTP]、セクション 15.4.3) または 307 (Temporary Redirect、[HTTP]、セクション 15.4.8) のいずれかの応答は、ターゲットリソースが一時的に移動したことを示します。4 つのケースすべてにおいて、サーバーは、ユーザーエージェントが、Location によって参照される新しいターゲット URI に同様の QUERY リクエストを送信することによって、元の QUERY リクエストを達成できることを示唆しています。

Note that the exceptions for redirecting a POST as a GET request after a 301 or 302 response do not apply to QUERY requests.

301 または 302 応答の後に POST を GET リクエストとしてリダイレクトする場合の例外は、QUERY リクエストには適用されないことに注意してください。

A response to QUERY with the status code 303 (See Other, Section 15.4.4 of [HTTP]) indicates that the original query can be accomplished via a normal retrieval request on the URI referenced by the Location response field ([HTTP], Section 10.2.2). For HTTP, this means sending a GET request to the new target URI, as illustrated by the example in Appendix A.4.3.

ステータスコード 303 による QUERY への応答 ([HTTP] のその他、セクション 15.4.4 を参照) は、元のクエリが、Location 応答フィールド ([HTTP]、セクション 10.2.2) で参照される URI に対する通常の取得リクエストを介して実行できることを示します。HTTP の場合、これは、付録 A.4.3 の例に示すように、新しいターゲット URI に GET リクエストを送信することを意味します。

2.6. Conditional Requests

2.6. 条件付きリクエスト

The selected representation (Section 3.2 of [HTTP]) of a QUERY request is the same as for a GET request to the equivalent resource (Section 2.2) of that QUERY request.

QUERY リクエストの選択された表現 ([HTTP] のセクション 3.2) は、その QUERY リクエストの同等のリソースに対する GET リクエスト (セクション 2.2) と同じです。

A conditional QUERY requests that the selected representation (i.e., the query results after any content negotiation) be returned in the response only under the circumstances described by the conditional header field(s), as defined in Section 13 of [HTTP].

条件付きクエリは、[HTTP] のセクション 13 で定義されているように、条件付きヘッダーフィールドで記述された状況下でのみ、選択された表現 (つまり、コンテンツネゴシエーション後のクエリ結果) が応答で返されることを要求します。

See Appendix A.5 for examples.

例については、付録 A.5 を参照してください。

2.7. Caching

2.7. キャッシング

The response to a QUERY method is cacheable; a cache MAY use it to satisfy subsequent QUERY requests as per Section 4 of [HTTP-CACHING].

QUERY メソッドへの応答はキャッシュ可能です。[HTTP-CACHING] のセクション 4 に従って、キャッシュは後続の QUERY リクエストを満たすためにそれを使用してもよい (MAY)。

The cache key for a QUERY request (Section 2 of [HTTP-CACHING]) MUST incorporate the request content (Section 6 of [HTTP-CACHING]) and related metadata (Section 8 of [HTTP]).

QUERY リクエストのキャッシュキー ([HTTP-CACHING] のセクション 2) には、リクエストのコンテンツ ([HTTP-CACHING] のセクション 6) および関連するメタデータ ([HTTP] のセクション 8) を組み込む必要があります。

To improve cache efficiency, caches MAY remove semantically insignificant differences from request content and related metadata first. For instance, by:

キャッシュ効率を向上させるために、キャッシュは、リクエストのコンテンツおよび関連するメタデータから意味的に重要でない差異を最初に削除してもよい(MAY)。たとえば、次のようにします。

* removing content encoding(s) (Section 8.4 of [HTTP]).

* コンテンツのエンコーディングを削除する ([HTTP] のセクション 8.4)。

* normalizing based upon knowledge of format conventions, as indicated by any media subtype suffix in the request's Content-Type field (e.g., "+json"; see Section 4.2.8 of [RFC6838]).

* リクエストの Content-Type フィールドのメディアサブタイプサフィックス (例: "+json"、[RFC6838] のセクション 4.2.8 を参照) によって示される形式規約の知識に基づいて正規化します。

* normalizing based upon knowledge of the semantics of the content itself, as indicated by the request's Content-Type field.

* リクエストの Content-Type フィールドによって示される、コンテンツ自体のセマンティクスの知識に基づいて正規化します。

Note that any such transformation is performed solely for the purpose of generating a cache key; it does not change the request itself.

このような変換はキャッシュキーを生成する目的のみで実行されることに注意してください。リクエスト自体は変更されません。

Clients can indicate, using the "no-transform" cache directive (Section 5.2.1.6 of [HTTP-CACHING]) that they wish that no such transformation happens (but note that this directive is just advisory).

クライアントは、「no-transform」キャッシュディレクティブ ([HTTP-CACHING] のセクション 5.2.1.6) を使用して、そのような変換が行われないことを希望することを示すことができます (ただし、このディレクティブは単なる助言であることに注意してください)。

Note that caching QUERY method responses is inherently more complex than caching responses to GET, as complete reading of the request's content is needed in order to determine the cache key. If a QUERY response supplies a Location response field (Section 2.4) to indicate a URI for an equivalent resource (Section 2.2), clients can switch to GET for subsequent requests, thereby simplifying processing.

キャッシュキーを決定するにはリクエストのコンテンツを完全に読み取る必要があるため、QUERY メソッドの応答のキャッシュは GET への応答のキャッシュよりも本質的に複雑であることに注意してください。QUERY 応答で、同等のリソース (セクション 2.2) の URI を示す Location 応答フィールド (セクション 2.4) が提供される場合、クライアントは後続のリクエストに対して GET に切り替えることができるため、処理が簡素化されます。

2.8. Range Requests

2.8. 範囲リクエスト

The semantics of Range Requests for QUERY are identical to those for GET, as defined in Section 14 of [HTTP]. Byte Range Requests (the only range unit defined at the time of writing), however, offer little value for the results of a QUERY request.

QUERY の範囲リクエストのセマンティクスは、[HTTP] のセクション 14 で定義されている GET のセマンティクスと同じです。ただし、バイト範囲リクエスト (執筆時点で定義されている唯一の範囲単位) は、QUERY リクエストの結果にはほとんど価値をもたらしません。

Query formats often define their own way of limiting or paging through result sets, such as with "FETCH FIRST ... ROWS ONLY" in SQL. It is expected that these built-in features will be used instead of HTTP Range Requests.

クエリ形式では、SQL の "FETCH FIRST ... ROWS ONLY" など、結果セットを制限またはページングする独自の方法が定義されることがよくあります。これらの組み込み機能は、HTTP 範囲リクエストの代わりに使用されることが予想されます。

3. The Accept-Query Header Field

3. Accept-Query ヘッダーフィールド

The "Accept-Query" response header field can be used by a resource to directly signal support for the QUERY method while identifying the specific query format media type(s) that may be used.

「Accept-Query」応答ヘッダーフィールドは、使用できる特定のクエリ形式メディアタイプを識別しながら、QUERY メソッドのサポートを直接通知するためにリソースによって使用されます。

Accept-Query contains a list of media ranges (Section 12.5.1 of [HTTP]) using "Structured Fields" syntax [STRUCTURED-FIELDS]. Media ranges are represented by a List Structured Header Field of either Tokens or Strings, containing the media range value without parameters.

Accept-Query には、「構造化フィールド」構文 [STRUCTURED-FIELDS] を使用したメディア範囲のリスト ([HTTP] のセクション 12.5.1) が含まれています。メディア範囲は、パラメータなしのメディア範囲値を含む、トークンまたは文字列のリスト構造化ヘッダーフィールドによって表されます。

Media type parameters, if any, are mapped to Structured Field Parameters with the String or Token type. The choice of Token versus String is semantically insignificant. That is, recipients MAY convert Tokens to Strings, but MUST NOT process them differently based on the received type.

メディアタイプパラメータがある場合は、文字列またはトークンタイプの構造化フィールドパラメータにマッピングされます。トークンと文字列の選択は意味的には重要ではありません。つまり、受信者はトークンを文字列に変換してもよい(MAY)が、受信した型に基づいてトークンを異なる方法で処理してはなりません(MUST NOT)。

Media types do not exactly map to Tokens; for instance, they allow a leading digit. In cases like these, the String format needs to be used.

メディアタイプはトークンに正確にマッピングされません。たとえば、先頭に数字を付けることができます。このような場合は、文字列形式を使用する必要があります。

The only supported uses of wildcards are "*/*", which matches any type, or "xxxx/*", which matches any subtype of the indicated type.

サポートされているワイルドカードの使用は、任意のタイプに一致する「*/*」、または指定されたタイプの任意のサブタイプに一致する「xxxx/*」のみです。

The order of types listed in the field value is not significant.

フィールド値にリストされるタイプの順序は重要ではありません。

The value of the Accept-Query field applies to every URI on the server that shares the same path; in other words, the query component is ignored. If requests to the same resource return different Accept-Query values, the most recently received fresh value (per Section 4.2 of [HTTP-CACHING]) is used.

Accept-Query フィールドの値は、同じパスを共有するサーバー上のすべての URI に適用されます。つまり、クエリコンポーネントは無視されます。同じリソースへのリクエストが異なる Accept-Query 値を返した場合、最後に受信した新しい値 ([HTTP-CACHING] のセクション 4.2 に従って) が使用されます。

For example:

例えば：

   Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

Although the syntax for this field appears to be similar to other fields, such as "Accept" (Section 12.5.1 of [HTTP]), it is a Structured Field and thus MUST be processed as specified in Section 4 of [STRUCTURED-FIELDS].

このフィールドの構文は、「Accept」([HTTP] のセクション 12.5.1) などの他のフィールドと似ているように見えますが、構造化フィールドであるため、[STRUCTURED-FIELDS] のセクション 4 で指定されているように処理しなければなりません (MUST)。

4. Security Considerations

4. セキュリティに関する考慮事項

The QUERY method is subject to the same general security considerations as all HTTP methods as described in [HTTP].

QUERY メソッドには、[HTTP] で説明されているすべての HTTP メソッドと同じ一般的なセキュリティ考慮事項が適用されます。

It can be used as an alternative to passing request information in the URI (e.g., in the query component). This is preferred in some cases, as the URI is more likely to be logged or otherwise processed by intermediaries than the request content. In other cases, where the query contains sensitive information, the potential for logging of the URI might motivate the use of QUERY over GET.

これは、リクエスト情報を URI (クエリコンポーネントなど) で渡す代わりに使用できます。URI はリクエストの内容よりも仲介者によってログに記録されるか、その他の方法で処理される可能性が高いため、場合によってはこれが推奨されます。クエリに機密情報が含まれる場合、URI のログが記録される可能性があるため、GET ではなく QUERY を使用する可能性があります。

If a server creates a temporary resource to represent the results of a QUERY request (e.g., for use in the Location or Content-Location field), assigns a URI to that resource, and the request contains sensitive information that cannot be logged, then that URI SHOULD be chosen such that it does not include any sensitive portions of the original request content.

サーバーが QUERY リクエストの結果を表す一時リソースを作成し (たとえば、Location または Content-Location フィールドで使用するため)、そのリソースに URI を割り当て、そのリクエストにログに記録できない機密情報が含まれている場合、その URI は、元のリクエストのコンテンツの機密部分が含まれないように選択されるべきです(SHOULD)。

Caches that normalize QUERY content incorrectly or in ways that are significantly different from how the resource processes the content can return an incorrect response if normalization results in a false positive.

QUERY コンテンツを誤って正規化するキャッシュ、またはリソースによるコンテンツの処理方法と大きく異なる方法で正規化するキャッシュでは、正規化の結果が誤検知となった場合、誤った応答が返される可能性があります。

A QUERY request from user agents implementing Cross-Origin Resource Sharing (CORS) will require a "preflight" request, as QUERY does not belong to the set of CORS-safelisted methods (see [FETCH]).

Cross-Origin Resource Sharing (CORS) を実装するユーザーエージェントからの QUERY リクエストには、「プリフライト」リクエストが必要です。これは、QUERY が CORS セーフリストに登録されたメソッドのセットに属していないためです ([FETCH] を参照)。

5. IANA Considerations

5. IANAの考慮事項

5.1. Registration of the QUERY Method

5.1. QUERYメソッドの登録

IANA has added the QUERY method to the "Hypertext Transfer Protocol (HTTP) Method Registry" at <http://www.iana.org/assignments/http-methods> (see Section 16.3.1 of [HTTP]).

IANA は、<http://www.iana.org/assignments/http-methods> にある「ハイパーテキスト転送プロトコル (HTTP) メソッドレジストリ」に QUERY メソッドを追加しました ([HTTP] のセクション 16.3.1 を参照)。

       +=============+======+============+========================+
       | Method Name | Safe | Idempotent | Specification          |
       +=============+======+============+========================+
       | QUERY       | yes  | yes        | Section 2 of RFC 10008 |
       +-------------+------+------------+------------------------+

Table 2: QUERY Method Definition

表 2: QUERY メソッドの定義

5.2. Registration of the Accept-Query Field

5.2. Accept-Queryフィールドの登録

IANA has added the Accept-Query field to the "Hypertext Transfer Protocol (HTTP) Field Name Registry" at <https://www.iana.org/assignments/http-fields> (see Section 16.1.1 of [HTTP]).

IANA は、Accept-Query フィールドを <https://www.iana.org/assignments/http-fields> の「ハイパーテキスト転送プロトコル (HTTP) フィールド名レジストリ」に追加しました ([HTTP] のセクション 16.1.1 を参照)。

    +==============+===========+============+==============+==========+
    | Field Name   | Status    | Structured | Reference    | Comments |
    |              |           | Type       |              |          |
    +==============+===========+============+==============+==========+
    | Accept-Query | permanent | List       | Section 3 of |          |
    |              |           |            | RFC 10008    |          |
    +--------------+-----------+------------+--------------+----------+

Table 3: Accept-Query Field Definition

表 3: Accept-Query フィールドの定義

6. References

6. 参考文献

6.1. Normative References

6.1. 引用文献

   [HTTP]     Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/info/rfc9110>.

   [HTTP-CACHING]
              Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Caching", STD 98, RFC 9111,
              DOI 10.17487/RFC9111, June 2022,
              <https://www.rfc-editor.org/info/rfc9111>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [STRUCTURED-FIELDS]
              Nottingham, M. and P. Kamp, "Structured Field Values for
              HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
              <https://www.rfc-editor.org/info/rfc9651>.

   [URI]      Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <https://www.rfc-editor.org/info/rfc3986>.

6.2. Informative References

6.2. 参考引用

   [FETCH]    WHATWG, "FETCH", WHATWG Living Standard,
              <https://fetch.spec.whatwg.org>.  Commit snapshot:
              <https://fetch.spec.whatwg.org/commit-
              snapshots/3bab31a55154bda73f25b45a23df718616f2f64e/>.

   [RFC3253]  Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
              Whitehead, "Versioning Extensions to WebDAV (Web
              Distributed Authoring and Versioning)", RFC 3253,
              DOI 10.17487/RFC3253, March 2002,
              <https://www.rfc-editor.org/info/rfc3253>.

   [RFC4918]  Dusseault, L., Ed., "HTTP Extensions for Web Distributed
              Authoring and Versioning (WebDAV)", RFC 4918,
              DOI 10.17487/RFC4918, June 2007,
              <https://www.rfc-editor.org/info/rfc4918>.

   [RFC5323]  Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich,
              "Web Distributed Authoring and Versioning (WebDAV)
              SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008,
              <https://www.rfc-editor.org/info/rfc5323>.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, DOI 10.17487/RFC6838, January 2013,
              <https://www.rfc-editor.org/info/rfc6838>.

   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

   [RFC9535]  Gössner, S., Ed., Normington, G., Ed., and C. Bormann,
              Ed., "JSONPath: Query Expressions for JSON", RFC 9535,
              DOI 10.17487/RFC9535, February 2024,
              <https://www.rfc-editor.org/info/rfc9535>.

   [URL]      WHATWG, "URL", WHATWG Living Standard,
              <https://url.spec.whatwg.org>.  Commit snapshot:
              <https://url.spec.whatwg.org/commit-
              snapshots/52526653e848c5a56598c84aa4bc8ac9025fb66b/>.

   [XSLT]     Kay, M., Ed., "XSL Transformations (XSLT) Version 3.0",
              W3C Recommendation, 8 June 2017,
              <https://www.w3.org/TR/2017/REC-xslt-30-20170608/>.
              Latest version available at
              https://www.w3.org/TR/xslt-30/.

Appendix A. Examples

付録A. 例

The examples below are for illustrative purposes only; if one needs to send queries that are actually this short, it is likely better to use GET.

以下の例は、説明のみを目的としています。実際にこれほど短いクエリを送信する必要がある場合は、GET を使用する方がよいでしょう。

The media type used in most examples is "application/x-www-form-urlencoded" (as used in POST requests from browser user clients, defined in "application/x-www-form-urlencoded" (https://url.spec.whatwg.org/#application/x-www-form-urlencoded) in [URL]). The Content-Length fields have been omitted for brevity.

ほとんどの例で使用されるメディアタイプは「application/x-www-form-urlencoded」です (ブラウザユーザークライアントからの POST リクエストで使用され、[URL] の「application/x-www-form-urlencoded」(https://url.spec.whatwg.org/#application/x-www-form-urlencoded) で定義されています)。簡潔にするために、Content-Length フィールドは省略されています。

A.1. Simple Query

A.1. 単純なクエリ

Below is a simple query with a direct response:

以下は、直接応答を含む単純なクエリです。

   QUERY /contacts HTTP/1.1
   Host: example.org
   Content-Type: application/x-www-form-urlencoded
   Accept: application/json

   select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

Response:

応答：

   HTTP/1.1 200 OK
   Content-Type: application/json

   [
     { "surname": "Smith",
       "givenname": "John",
       "email": "smith@example.org" },
     { "surname": "Jones",
       "givenname": "Sally",
       "email": "sally.jones@example.com" },
     { "surname": "Dubois",
       "givenname": "Camille",
       "email": "camille.dubois@example.net" }
   ]

A.2. Discovery of QUERY Support

A.2. QUERYサポートの発見

A simple way to discover support for QUERY is provided by the OPTIONS (Section 9.3.7 of [HTTP]) method:

QUERY のサポートを見つける簡単な方法は、OPTIONS ([HTTP] のセクション 9.3.7) メソッドによって提供されます。

   OPTIONS /contacts HTTP/1.1
   Host: example.org

Response:

応答：

   HTTP/1.1 200 OK
   Allow: GET, QUERY, OPTIONS, HEAD

The Allow response field (Section 10.2.1 of [HTTP]) denotes the set of supported methods on the specified resource.

「応答を許可」フィールド ([HTTP] のセクション 10.2.1) は、指定されたリソースでサポートされているメソッドのセットを示します。

There are alternatives to the use of OPTIONS. For instance, a QUERY request can be tried without prior knowledge of server support. The server would then either process the request, or it could respond with a 4xx status such as 405 (Method Not Allowed, Section 15.5.6 of [HTTP]), including the Allow response field.

OPTIONS の使用に代わる方法があります。たとえば、サーバーサポートに関する事前知識がなくても、QUERY リクエストを試すことができます。その後、サーバーはリクエストを処理するか、「応答を許可」フィールドを含む 405 (メソッドは許可されていません、[HTTP] のセクション 15.5.6) などの 4xx ステータスで応答します。

A.3. Discovery of QUERY Formats

A.3. QUERYフォーマットの発見

The discovery of supported media types for QUERY is possible via the Accept-Query response field (Section 3):

QUERY でサポートされているメディアタイプの検出は、Accept-Query 応答フィールド (セクション 3) を介して可能です。

   HEAD /contacts HTTP/1.1
   Host: example.org

Response:

応答：

   HTTP/1.1 200 OK
   Content-Type: application/xhtml
   Accept-Query: application/x-www-form-urlencoded, application/sql

Responses to which request methods will contain Accept-Query will depend on the resource being accessed.

どのリクエストメソッドに対する応答に Accept-Query が含まれるかは、アクセスされるリソースによって異なります。

An alternative to checking Accept-Query would be to make a QUERY request, and then -- in case of a 4xx status such as a 415 response (Unsupported Media Type, Section 15.5.16 of [HTTP]) -- to inspect the Accept response field (Section 12.5.1 of [HTTP]):

Accept-Query をチェックする代わりに、QUERY リクエストを作成し、次に 415 応答 (サポートされていないメディアタイプ、[HTTP] のセクション 15.5.16) などの 4xx ステータスの場合に -- Accept 応答フィールド ([HTTP] のセクション 12.5.1) を検査することもできます。

   HTTP/1.1 415 Unsupported Media Type
   Content-Type: application/xhtml
   Accept: application/x-www-form-urlencoded, application/sql

A.4. Content-Location, Location, and Indirect Responses

A.4. コンテンツ - 場所、場所、および間接的な応答

As described in Sections 2.3 and 2.4, the Content-Location and Location response fields in success responses (2xx, Section 15.3 of [HTTP]) provide a way to identify alternate resources that will respond to GET requests, either for the received result of the request or for future requests to perform the same operation. Going back to the example from Appendix A.1:

セクション 2.3 および 2.4 で説明されているように、成功応答の Content-Location および Location 応答フィールド (2xx、[HTTP] のセクション 15.3) は、受信した要求の結果または同じ操作を実行する将来の要求のいずれかに対して、GET 要求に応答する代替リソースを識別する方法を提供します。付録 A.1 の例に戻ります。

   QUERY /contacts HTTP/1.1
   Host: example.org
   Content-Type: application/x-www-form-urlencoded
   Accept: application/json

   select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

Response:

応答：

   HTTP/1.1 200 OK
   Content-Type: application/json
   Content-Location: /contacts/stored-results/17
   Location: /contacts/stored-queries/42
   Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
   Date: Sun, 17 Nov 2024, 16:10:24 GMT

   [
     { "surname": "Smith",
       "givenname": "John",
       "email": "smith@example.org" },
     { "surname": "Jones",
       "givenname": "Sally",
       "email": "sally.jones@example.com" },
     { "surname": "Dubois",
       "givenname": "Camille",
       "email": "camille.dubois@example.net" }
   ]

A.4.1. Using Content-Location

A.4.1. コンテンツの場所の使用

The Content-Location response field received above identifies a resource holding the result for the QUERY response it appeared on:

上記で受信した Content-Location 応答フィールドは、それが表示された QUERY 応答の結果を保持するリソースを識別します。

   GET /contacts/stored-results/17 HTTP/1.1
   Host: example.org
   Accept: application/json

Response:

応答：

   HTTP/1.1 200 OK
   Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
   Date: Sun, 17 Nov 2024, 16:10:25 GMT

   [
     { "surname": "Smith",
       "givenname": "John",
       "email": "smith@example.org" },
     { "surname": "Jones",
       "givenname": "Sally",
       "email": "sally.jones@example.com" },
     { "surname": "Dubois",
       "givenname": "Camille",
       "email": "camille.dubois@example.net" }
   ]

Note that there is no guarantee that the server will implement this resource indefinitely, so, after an error response, the client would need to redo the original QUERY request in order to obtain a new alternative location.

サーバーがこのリソースを無期限に実装するという保証はないので、エラー応答の後、クライアントは新しい代替の場所を取得するために元の QUERY リクエストをやり直す必要があることに注意してください。

A.4.2. Using Location

A.4.2. 位置情報の使用

The Location response field identifies a resource that will respond to GET with a current result for the same process and parameters as the original QUERY request.

Location 応答フィールドは、元の QUERY リクエストと同じプロセスおよびパラメータの現在の結果で GET に応答するリソースを識別します。

   GET /contacts/stored-queries/42 HTTP/1.1
   Host: example.org
   Accept: application/json

In this example, one entry was removed at 2024-11-17T16:12:01Z (as indicated in the Last-Modified field), so the response only contains two entries:

この例では、(Last-Modified フィールドに示されているように) 2024-11-17T16:12:01Z に 1 つのエントリが削除されたため、応答には 2 つのエントリのみが含まれます。

   HTTP/1.1 200 OK
   Content-Type: application/json
   Last-Modified: Sun, 17 November 2024, 16:12:01 GMT
   ETag: "42-1"
   Date: Sun, 17 Nov 2024, 16:13:17 GMT

   [
     { "surname": "Smith",
       "givenname": "John",
       "email": "smith@example.org" },
     { "surname": "Dubois",
       "givenname": "Camille",
       "email": "camille.dubois@example.net" }
   ]

Assuming that the server still exposes the resource and that there was no change in the query result, a subsequent conditional GET request with the following:

サーバーがまだリソースを公開しており、クエリ結果に変更がないと仮定すると、後続の条件付き GET リクエストは次のようになります。

   If-None-Match: "42-1"

would result in a 304 (Not Modified) response (Section 15.4.5 of [HTTP]).

304 (Not Modified) 応答が返されます ([HTTP] のセクション 15.4.5)。

A.4.3. Indirect Responses

A.4.3. 間接的な応答

Servers can send "indirect" responses (Section 2.5) using the status code 303 (See Other, Section 15.4.4 of [HTTP]).

サーバーは、ステータスコード 303 を使用して「間接的な」応答 (セクション 2.5) を送信できます (その他、[HTTP] のセクション 15.4.4 を参照)。

Given the request at the beginning of Appendix A.4, a server might respond with:

付録 A.4 の冒頭にあるリクエストを考慮すると、サーバーは次のように応答する可能性があります。

   HTTP/1.1 303 See Other
   Content-Type: text/plain
   Date: Sun, 17 Nov 2024, 16:13:17 GMT
   Location: /contacts/stored-queries/42

   See stored query at "/contacts/stored-queries/42".

This is similar to including Location on a direct response, except that no result for the query is returned. This allows the server to only generate or reuse an alternative resource. This resource could then be used as shown in Appendix A.4.2.

これは、クエリの結果が返されないことを除いて、直接応答に Location を含めることに似ています。これにより、サーバーは代替リソースを生成または再利用することのみが可能になります。このリソースは、付録 A.4.2 に示すように使用できます。

A.5. Conditional Requests

A.5. 条件付きリクエスト

Consider a resource implementing QUERY that supports "application/ sql" and "application/xslt+xml" [XSLT] as request media types, and which can generate responses as "text/csv". The data set being queried contains RFC document information, and the query returns information grouped by decade:

要求メディアタイプとして "application/sql" および "application/xslt+xml" [XSLT] をサポートし、応答を "text/csv" として生成できる QUERY を実装するリソースを考えてみましょう。クエリ対象のデータセットには RFC 文書情報が含まれており、クエリは 10 年ごとにグループ化された情報を返します。

   QUERY /rfc-index.xml HTTP/1.1
   Host: example.org
   Date: Sun, 7 Sep 2025, 00:00:00 GMT
   Content-Type: application/xslt+xml
   Accept: text/csv

   ...Query content using XSLT...

Response:

応答：

   HTTP/1.1 200 OK
   Date: Sun, 7 Sep 2025, 00:00:00 GMT
   Location: /stored-queries/4815162342
   Content-Type: text/csv
   Accept-Query: "application/sql", "application/xslt+xml"
   Last-Modified: Sun, 31 Aug 2025, 08:44:00 GMT
   Vary: Accept-Query, Content-Encoding, Content-Type

   decade, total, with errata, % with errata, average page count
   1960, 26, 5, 19.2, 5.3
   1970, 666, 18, 2.7, 6.1
   1980, 376, 44, 11.7, 23.4
   1990, 1593, 269, 16.9, 25.5
   2000, 2888, 1048, 36.3, 27.3
   2010, 2954, 895, 30.3, 26.1
   2020, 1133, 230, 20.3, 26.2

Here, the server has assigned the path "/stored-queries/4815162342" to the equivalent resource (Section 2.4) for subsequent use with GET.

ここで、サーバーは、後で GET で使用できるように、パス「/stored-queries/4815162342」を同等のリソース (セクション 2.4) に割り当てています。

Later on, the client repeats the query, but specifies that results should only be returned when changed:

その後、クライアントはクエリを繰り返しますが、結果が変更された場合にのみ返されるように指定します。

   QUERY /rfc-index.xml HTTP/1.1
   Host: example.org
   Date: Mon, 8, Sep 2025, 11:00:00 GMT
   Content-Type: application/sql
   Accept: text/csv
   If-Modified-Since: Sun, 31 Aug 2025, 08:44:00 GMT
   Vary: Accept-Query, Content-Type

   ...Same query, but using SQL...

The data being queried did not change, therefore the server responds with:

クエリ対象のデータは変更されていないため、サーバーは次のように応答します。

   HTTP/1.1 304 Not Modified
   Date: Mon, 8 Sep 2025, 11:00:00 GMT
   Content-Type: text/csv
   Location: /stored-queries/4815162342
   Accept-Query: "application/sql", "application/xslt+xml"
   Last-Modified: Sun, 31 Aug 2025, 08:44:00 GMT
   Vary: Accept-Query, Content-Type

As the server identified a URI for the equivalent resource, that resource can be accessed with GET. In particular, this avoids resending the query request's content:

サーバーは同等のリソースの URI を識別したため、そのリソースには GET でアクセスできます。特に、これによりクエリリクエストのコンテンツの再送信が回避されます。

   GET /stored-queries/4815162342 HTTP/1.1
   Host: example.org
   Date: Sun, 21, Sep 2025, 12:08:00 GMT
   Accept: text/csv
   If-Modified-Since: Sun, 31 Aug 2025, 00:00:00 GMT

Here, the state of the data set indeed changed, so new content is returned:

ここでは、データセットの状態が実際に変更されたため、新しいコンテンツが返されます。

   HTTP/1.1 200 OK
   Date: Sun, 21, Sep 2025, 12:08:00 GMT
   Content-Type: text/csv
   Last-Modified: Thu, 18 Sep 2025, 19:56:00 GMT
   Vary: Accept-Query, Content-Encoding, Content-Type

   decade, total, with errata, % with errata, average page count
   1960, 26, 5, 19.2, 5.3
   1970, 666, 18, 2.7, 6.1
   1980, 376, 44, 11.7, 23.4
   1990, 1593, 269, 16.9, 25.5
   2000, 2888, 1048, 36.3, 27.3
   2010, 2954, 895, 30.3, 26.1
   2020, 1133, 230, 20.3, 26.2

(Note the change in the row for this decade.)

(この 10 年間の行の変化に注目してください。)

The diagrams below illustrate the use of conditional requests and how they can differ when a URI is assigned to the equivalent resource (and when the client is taking advantage of it). The fictitious field name "Validator" is used for demonstration purposes.

以下の図は、条件付きリクエストの使用法と、URI が同等のリソースに割り当てられている場合 (およびクライアントがそれを利用している場合) にどのような違いがあるかを示しています。架空のフィールド名「Validator」は、デモンストレーションの目的で使用されています。

            Client                             Resource
            |                                         |
            | QUERY with content                      |
            +---------------------------------------->|
            |                                         |
            |                                  200 OK |
            |                          Validator: foo |
            |<----------------------------------------+
            |                                         |
            | QUERY with content                      |
            | (conditional on 'foo')                  |
            +---------------------------------------->|
            |                                         |
            |                        304 Not Modified |
            |                          Validator: foo |
            |<----------------------------------------+
            |                                         |
            |                                  +--------------+
            |                                  | State Change |
            |                                  +--------------+
            |                                         |
            | QUERY with content                      |
            | (conditional on 'foo')                  |
            +---------------------------------------->|
            |                                         |
            |                                  200 OK |
            |                          Validator: bar |
            |<----------------------------------------+
            |                                         |

Figure 1: Data Flow with QUERY Only

図 1: QUERY のみのデータフロー

   Client                   Resource
   |                               |
   | QUERY with content            |         Equivalent Resource
   +------------------------------>|            (generates /xyz)
   |                               +---------------------------o
   |                               |                           |
   |                        200 OK |                           |
   |                Validator: foo |                           |
   |                Location: /xyz |                           |
   |<------------------------------+                           |
   |                               |                           |
   | GET                                                       |
   | (conditional on 'foo')                                    |
   +---------------------------------------------------------->|
   |                                                           |
   |                                          304 Not Modified |
   |                                            Validator: foo |
   |<----------------------------------------------------------+
   |                                                           |
   |                                                    +--------------+
   |                                                    | State Change |
   |                                                    +--------------+
   | GET                                                       |
   | (conditional on 'foo')                                    |
   +---------------------------------------------------------->|
   |                                                           |
   |                                                    200 OK |
   |                                            Validator: bar |
   |<----------------------------------------------------------+
   |                                                           |

Figure 2: Data Flow with GET to Equivalent Resource

図 2: 同等のリソースへの GET によるデータフロー

A.6. More Query Formats

A.6. その他のクエリ形式

The following examples show requests on a JSON-shaped [RFC8259] database of RFC errata.

次の例は、RFC 正誤表の JSON 形式 [RFC8259] データベースに対するリクエストを示しています。

The request below uses eXtensible Stylesheet Language Transformations (XSLT) to extract errata information summarized per year and the defined errata types.

以下のリクエストでは、eXtensible Stylesheet Language Transformations (XSLT) を使用して、年ごとに要約されたエラータ情報と定義されたエラータタイプを抽出します。

   QUERY /errata.json HTTP/1.1
   Host: example.org
   Content-Type: application/xslt+xml
   Accept: application/xml, text/csv

   <transform xmlns="http://www.w3.org/1999/XSL/Transform"
     xmlns:j="http://www.w3.org/2005/xpath-functions"
     version="3.0">

     <output method="text"/>

     <param name="input"/>

     <variable name="json"
       select="json-to-xml(unparsed-text($input))"/>

     <variable name="sc">errata_status_code</variable>
     <variable name="sd">submit_date</variable>

     <template match="/">
       <text>year, total, rejected, verified, hdu, reported</text>
       <text>&#10;</text>
       <variable name="en" select="$json//j:map"/>
       <for-each-group select="$en"
         group-by="substring-before(j:string[@key=$sd],'-')">
         <sort select="current-grouping-key()"/>
         <variable name="year" select="current-grouping-key()"/>
         <variable name="errata" select=
           "$en[$year=substring-before(j:string[@key=$sd],'-')]"/>
         <value-of select="concat(
           $year,
           ', ',
           count($errata),
           ', ',
           count($errata['Rejected'=j:string[@key=$sc]]),
           ', ',
           count($errata['Verified'=j:string[@key=$sc]]),
           ', ',
           count(
             $errata['Held for Document Update'=j:string[@key=$sc]]),
           ', ',
           count($errata['Reported'=j:string[@key=$sc]]),
           '&#10;')"/>
       </for-each-group>
     </template>

   </transform>

Response:

応答：

   HTTP/1.1 200 OK
   Content-Type: text/csv
   Accept-Query: "application/jsonpath", "application/xslt+xml"
   Date: Wed, 19 Feb 2025, 17:10:01 GMT

   year, total, rejected, verified, hdu, reported
   2000, 14, 0, 14, 0, 0
   2001, 72, 1, 70, 1, 0
   2002, 124, 8, 104, 12, 0
   2003, 63, 0, 61, 2, 0
   2004, 89, 1, 83, 5, 0
   2005, 156, 10, 96, 50, 0
   2006, 444, 54, 176, 214, 0
   2007, 429, 48, 188, 193, 0
   2008, 423, 52, 165, 206, 0
   2009, 331, 39, 148, 144, 0
   2010, 538, 80, 232, 222, 4
   2011, 367, 47, 170, 150, 0
   2012, 348, 54, 149, 145, 0
   2013, 341, 61, 169, 106, 5
   2014, 342, 73, 180, 72, 17
   2015, 343, 79, 145, 89, 30
   2016, 295, 46, 122, 82, 45
   2017, 303, 46, 120, 84, 53
   2018, 350, 61, 118, 98, 73
   2019, 335, 47, 131, 94, 63
   2020, 387, 68, 117, 123, 79
   2021, 321, 44, 148, 63, 66
   2022, 358, 37, 198, 40, 83
   2023, 262, 38, 121, 33, 70
   2024, 322, 33, 125, 23, 141
   9999, 1, 0, 0, 1, 0

Note the Accept-Query response field indicating that another query format, JSONPath [RFC9535], is supported as well. The request below would report the identifiers of all rejected errata submitted since 2024:

Accept-Query 応答フィールドは、別のクエリ形式である JSONPath [RFC9535] もサポートされていることを示していることに注意してください。以下のリクエストは、2024 年以降に送信され、拒否されたすべてのエラッタの識別子を報告します。

   QUERY /errata.json HTTP/1.1
   Host: example.org
   Content-Type: application/jsonpath
   Accept: application/json

   $..[
        ?@.errata_status_code=="Rejected"
        && @.submit_date>"2024"
      ]
      ["doc-id"]

Response:

応答：

   HTTP/1.1 200 OK
   Content-Type: application/json
   Accept-Query: "application/jsonpath", "application/xslt+xml"
   Date: Thu, 20 Feb 2025, 09:55:42 GMT
   Last-Modified: Thu, 20 Feb 2025 06:10:01 GMT

   [
     "RFC1185","RFC8407","RFC6350","RFC8467","RFC1157","RFC9543",
     "RFC9076","RFC7656","RFC2822","RFC9460","RFC2104","RFC6797",
     "RFC9499","RFC9557","RFC2131","RFC2328","RFC9001","RFC3325",
     "RFC9438","RFC2526","RFC2985","RFC7643","RFC9132","RFC6376",
     "RFC9110","RFC9460","RFC7748","RFC9497","RFC8463","RFC4035",
     "RFC7239","RFC9083","RFC9537","RFC9537","RFC9420","RFC9000",
     "RFC9656","RFC9110","RFC2324","RFC2549","RFC6797","RFC2549",
     "RFC8894"
   ]

Appendix B. Selection of the Method Name 'QUERY'

付録B. メソッド名「QUERY」の選択

The "Hypertext Transfer Protocol (HTTP) Method Registry" (<http://www.iana.org/assignments/http-methods>) already contains three other methods with the properties "safe" and "idempotent": "PROPFIND" [RFC4918], "REPORT" [RFC3253], and "SEARCH" [RFC5323].

「ハイパーテキスト転送プロトコル (HTTP) メソッドレジストリ」 (<http://www.iana.org/assignments/http-methods>) には、「安全」および「冪等」プロパティを持つ他の 3 つのメソッド、「PROPFIND」 [RFC4918]、「REPORT」 [RFC3253]、および「SEARCH」 [RFC5323] がすでに含まれています。

It would have been possible to reuse any of these, updating it in a way that it matches what this specification defines as the new method "QUERY". Indeed, the early stages of this specification used "SEARCH".

この仕様で新しいメソッド「QUERY」として定義されているものと一致する方法で更新して、これらのいずれかを再利用することも可能でした。実際、この仕様の初期段階では「SEARCH」が使用されていました。

The method name "QUERY" ultimately was chosen because:

メソッド名「QUERY」が最終的に選択された理由は次のとおりです。

* The alternatives use a generic media type for the request content ("application/xml"); the semantics of the request depend solely on the request content.

* 代替案では、リクエストのコンテンツに汎用メディアタイプ (「application/xml」) を使用します。リクエストのセマンティクスはリクエストの内容のみに依存します。

* Furthermore, they all originate from the WebDAV activity, about which many have mixed feelings.

* さらに、それらはすべて WebDAV アクティビティに由来しており、多くの人が複雑な感情を抱いています。

* "QUERY" captures the relation with the URI's query component well.

* 「QUERY」はURIのクエリコンポーネントとの関係をうまく捉えています。

Acknowledgements

謝辞

We thank all members of the HTTP Working Group for their ideas, reviews, and feedback.

アイデア、レビュー、フィードバックをくださった HTTP ワーキンググループのメンバー全員に感謝します。

The following individuals deserve special recognition: Carsten Bormann, Mark Nottingham, Martin Thomson, Michael Thornburgh, Roberto Polli, Roy Fielding, and Will Hawkins.

次の人物は特別な評価に値します: カーステン・ボルマン、マーク・ノッティンガム、マーティン・トムソン、マイケル・ソーンバーグ、ロベルト・ポーリ、ロイ・フィールディング、ウィル・ホーキンス。

Contributors

貢献者

Ashok Malhotra participated in early discussions leading to this specification:

Ashok Malhotra は、この仕様につながる初期の議論に参加しました。

   Ashok Malhotra
   Email: malhotrasahib@gmail.com

Discussion on this HTTP method was reopened by Asbjørn Ulsberg during the HTTP Workshop in 2019:

この HTTP メソッドに関する議論は、2019 年の HTTP ワークショップ中に Asbjørn Ulsberg によって再開されました。

   Asbjørn Ulsberg
   Email: asbjorn@ulsberg.no
   URI:   https://asbjor.nu/

Authors' Addresses

著者の住所

   Julian Reschke
   greenbytes GmbH
   Hafenweg 16
   48155 Münster
   Germany
   Email: julian.reschke@greenbytes.de
   URI:   https://greenbytes.de/tech/webdav/

   James M Snell
   Cloudflare
   Email: jasnell@gmail.com

   Mike Bishop
   Akamai
   Email: mbishop@evequefou.be

RFC 10008 - The HTTP QUERY Method 日本語訳

The HTTP QUERY Method

HTTP QUERY メソッド

Abstract

概要

Status of This Memo

本文書の状態

Copyright Notice

著作権表示

Table of Contents

目次

1. Introduction

1. はじめに

1.1. Terminology

1.1. 用語

1.2. Notational Conventions

1.2. 表記規則

2. QUERY Method

2. QUERYメソッド

2.1. Media Types and Content Negotiation

2.1. メディアタイプとコンテンツネゴシエーション

2.2. Equivalent Resource

2.2. 同等のリソース

2.3. Content-Location Response Field

2.3. コンテンツと場所の応答フィールド

2.4. Location Response Field

2.4. 位置応答フィールド

2.5. Redirection

2.5. リダイレクション

2.6. Conditional Requests

2.6. 条件付きリクエスト

2.7. Caching

2.7. キャッシング

2.8. Range Requests

2.8. 範囲リクエスト

3. The Accept-Query Header Field

3. Accept-Query ヘッダー フィールド

4. Security Considerations

4. セキュリティに関する考慮事項

5. IANA Considerations

5. IANAの考慮事項

5.1. Registration of the QUERY Method

5.1. QUERYメソッドの登録

5.2. Registration of the Accept-Query Field

5.2. Accept-Queryフィールドの登録

6. References

6. 参考文献

6.1. Normative References

6.1. 引用文献

6.2. Informative References

6.2. 参考引用

Appendix A. Examples

付録A. 例

A.1. Simple Query

A.1. 単純なクエリ

A.2. Discovery of QUERY Support

A.2. QUERYサポートの発見

A.3. Discovery of QUERY Formats

A.3. QUERYフォーマットの発見

A.4. Content-Location, Location, and Indirect Responses

A.4. コンテンツ - 場所、場所、および間接的な応答

A.4.1. Using Content-Location

A.4.1. コンテンツの場所の使用

A.4.2. Using Location

A.4.2. 位置情報の使用

A.4.3. Indirect Responses

A.4.3. 間接的な応答

A.5. Conditional Requests

A.5. 条件付きリクエスト

A.6. More Query Formats

A.6. その他のクエリ形式

Appendix B. Selection of the Method Name 'QUERY'

付録B. メソッド名「QUERY」の選択

Acknowledgements

謝辞

Contributors

貢献者

Authors' Addresses

著者の住所

3. Accept-Query ヘッダーフィールド