HTTP QUERY メソッド

本文書は、次に定義される用語を使用する: 第3節、[HTTP]。

さらに、URI のクエリ成分に含まれるパラメーターを指す用語として、URI クエリパラメーターを 使用する（第4.2.2節、 [HTTP]）。また、クエリ コンテンツは、リクエストコンテンツ（第6.4節、[HTTP]）のうち、QUERY リクエストのものを指す。

キーワード "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", および "OPTIONAL" は、本文書では、次に記述されるとおりに解釈される: BCP 14 [RFC2119] [RFC8174]。 ただし、ここに示すように、すべて大文字で現れる場合に限る。

QUERY リクエストの意味論は、リクエストコンテンツと、それに関連付けられた メタデータ（メディアタイプなど）の両方に依存する（[HTTP]、第8.3.1節）。 一般に、コンテンツとメタデータが整合しないリクエストに問題がある場合、必ず 4xx（クライアントエラー）応答によって拒否しなければならない（[HTTP]、第15.5節）。

• リクエストにメディアタイプ情報が欠けている場合、定義上、そのリクエストは不正であり、 400（クライアントエラー）などの 4xx ステータスコードで失敗させる必要がある。
• メディアタイプが指定されているが、リソースでサポートされていない場合、415 (Unsupported Media Type) が適切である。これには特に、 メディアタイプ自体は既知であるものの、対象リソースへの QUERY に固有の 意味論が存在しない場合が含まれる。いずれの場合も、Accept-Query 応答フィールド（第3節）を 使用して、サポートされるメディアタイプをクライアントに通知できる。
• メディアタイプが指定されているが、実際のリクエストコンテンツと整合しない場合、 400 (Bad Request) を返すことができる。すなわち、サーバーはリクエストコンテンツからメディア タイプを推測し、欠落した値や「誤った」値を上書きすることは許されない （すなわち、「コンテンツスニッフィング」）。
• メディアタイプが指定され、理解されており、コンテンツも実際にそのタイプと整合するが、 クエリの実際の内容が原因でクエリを処理できない場合、 ステータス 422 (Unprocessable Content) を使用できる。例としては、 存在しないテーブルを指定する、構文上は正しい SQL クエリが挙げられる。
• クライアントが Accept フィールドを使用して特定の応答メディアタイプを要求し（[HTTP]、第 12.5.1節）、それがリソースでサポートされていない場合、ステータスコード 406 (Not Acceptable) が適切である。

ある QUERY リクエストの等価なリソースは、GET リクエストに応答し、 その QUERY リクエストとその対象を表し、メッセージの コンテンツとメタデータの両方を考慮するリソースである（第6節、[HTTP]）。特に、これには、 表現メタデータ（第8節、[HTTP]）、たとえば コンテンツのメディアタイプが含まれる。

言い換えると、等価なリソースは、QUERY を実装するリソースから、 リクエストコンテンツを組み込むことによって導出される。

等価なリソースという用語は、選択された表現など、 HTTP の他の側面の動作を定義するための手段として使用される。サーバーは、 これらのリソースに URI を割り当てることができるが、その必要はない（第1.1節、[URI]を参照）。割り当てた 場合、これらのリソースには GET リクエストでアクセスできるようになる。

成功応答（2xx、第15.3節、 [HTTP]）には、 操作の結果に対応するリソースの識別子を含む Content-Location ヘッダーフィールドを 含めることができる。詳細は、第8.7節、[HTTP]を参照。これは、 クライアントが示された URI に対して GET リクエストを送信することで、 直前に実行されたクエリ操作の結果を取得できる、というサーバーの主張を表す。 示されたリソースは、一時的なものである可能性がある。

付録 A.4.1を 例として参照。

サーバーは、QUERY リクエストの等価なリソース（第2.2節）に URI を割り当てることができる。割り当てた 場合、そのリソースの URI を、2xx 応答の Location ヘッダーフィールドに 含めることができる（第10.2.2節、 [HTTP]を参照）。これは、 クライアントが示された URI に GET リクエストを送信することで、クエリコンテンツを再送信せずに、 直前に実行されたクエリ操作を繰り返せる、という主張を表す。このリソースの URI は、 一時的なものである可能性がある。将来のリクエストが失敗した場合、クライアントは、元の QUERY リクエスト対象と、以前に送信したコンテンツを使用して再試行できる。

付録 A.4.2を例として参照。

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

ステータスコード 301 (Moved Permanently、[HTTP]、第 15.4.2節）、または 308 (Permanent Redirect、[HTTP]、第 15.4.9節）の応答は、対象リソースが、Location 応答フィールドによって参照される別の URI に恒久的に移動したことを示す（[HTTP]、第 10.2.2節）。同様に、ステータスコード 302 (Found、[HTTP]、第 15.4.3節）、または 307 (Temporary Redirect、[HTTP]、第 15.4.8節）の応答は、対象リソースが一時的に移動したことを示す。これら4つの 場合のいずれにおいても、サーバーは、ユーザーエージェントが同様の QUERY リクエストを Location によって参照される新しい対象 URI に送信することで、元の QUERY リクエストを 達成できることを示唆している。

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

ステータスコード 303 (See Other、第15.4.4節、 [HTTP]）の QUERY への応答は、 元のクエリが、Location 応答フィールドによって参照される URI に対する通常の取得リクエストで 達成できることを示す（[HTTP]、第 10.2.2節）。HTTP では、これは、新しい対象 URI に GET リクエストを送信することを意味する。 この例は、付録 A.4.3に示されている。

選択された表現（第3.2節、[HTTP]）は、QUERY リクエストの場合、 その QUERY リクエストの等価なリソース（第2.2節）に対する GET リクエストの 場合と同じである。

条件付き QUERY は、選択された表現（すなわち、コンテンツネゴシエーション後のクエリ結果）を、 条件付きヘッダーフィールドに記述された状況においてのみ、 応答で返すことを要求する。これは、第13節、[HTTP]で定義されるとおりである。

付録 A.5を 例として参照。

QUERY メソッドへの応答はキャッシュ可能であり、キャッシュはこれを使用 してもよい。 その用途は、次に従って後続の QUERY リクエストを満たすことである: 第4節、[HTTP-CACHING]。

QUERY リクエストのキャッシュキー（第2節、[HTTP-CACHING]）には、必ず リクエストコンテンツ（第6節、[HTTP-CACHING]）と関連する メタデータ（第8節、 [HTTP]）を組み込まなければならない。

• コンテンツ符号化を除去する（第8.4節、 [HTTP]）。
• リクエストの Content-Type フィールドにあるメディアサブタイプの接尾辞が示す、 形式上の慣例に関する知識に基づいて正規化する（たとえば "+json"。第 4.2.8節、[RFC6838]を参照）。
• リクエストの Content-Type フィールドによって示される、 コンテンツ自体の意味論に関する知識に基づいて正規化する。

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

クライアントは、"no-transform" キャッシュ指令を使用して（第 5.2.1.6節、[HTTP-CACHING]）、このような変換が 行われないことを望む旨を示すことができる（ただし、この指令は助言にすぎない点に注意）。

QUERY メソッドへの応答のキャッシュ処理は、本質的に GET への応答のキャッシュ処理より複雑である。 キャッシュキーを決定するために、リクエストのコンテンツを完全に読み取る必要が あるためである。QUERY 応答が、Location 応答フィールド（第2.4節）を提供して、 等価なリソース（第2.2節）の URI を示す場合、クライアントは後続のリクエストを GET に切り替えることで、処理を簡素化できる。

QUERY の範囲リクエストの意味論は、GET のものと同じであり、 第14節、[HTTP]で定義されるとおりである。ただし、バイト範囲リクエスト （執筆時点で定義されている唯一の範囲単位）は、 QUERY リクエストの結果に対しては、ほとんど有用ではない。

クエリ形式は、結果集合を制限したり、ページ単位で取得したりする独自の方法を定義することが多い。 たとえば、SQL の "FETCH FIRST ... ROWS ONLY" がある。HTTP 範囲リクエストの代わりに、 これらの組み込み機能が使用されることが想定される。

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

IANA は、Accept-Query フィールドを「ハイパーテキスト転送プロトコル (HTTP) フィールド 名レジストリー」に追加した。その場所は <https://www.iana.org/assignments/http-fields> である（第 16.1.1節、[HTTP]を参照）。

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

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" }
]

OPTIONS /contacts HTTP/1.1
Host: example.org

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

Allow 応答フィールド（第10.2.1節、 [HTTP]）は、指定されたリソースで サポートされるメソッドの集合を示す。

OPTIONS の使用に代わる方法もある。たとえば、サーバーのサポートに関する事前知識なしに、 QUERY リクエストを試みることができる。その場合、サーバーはリクエストを 処理するか、あるいは 405 (Method Not Allowed、第15.5.6節、 [HTTP]）などの 4xx ステータスで、 Allow 応答フィールドを含めて応答することがある。

HEAD /contacts HTTP/1.1
Host: example.org

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

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

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

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

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" }
]

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

...XSLT を使用したクエリコンテンツ...

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

ここで、サーバーは、等価なリソースにパス "/stored-queries/4815162342" を 割り当てている（第2.4節）。 これは、後で GET とともに使用するためである。

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

...同じクエリだが、SQL を使用...

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

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

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

（現在の年代に対応する行の変更に注意。）

以下の図は、条件付きリクエストの使用と、 等価なリソースに URI が割り当てられた場合（およびクライアントが それを活用している場合）に、どのような違いが生じ得るかを示す。架空のフィールド名 "Validator" は、 説明のために使用している。

以下の例は、JSON 形式の [RFC8259] RFC 正誤情報データベースへのリクエストを示す。

以下のリクエストは、拡張可能スタイルシート言語変換 (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>

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

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"]

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"
]