HTTP 新增 QUERY 方法,RFC 10008 正式定义
来源标题:RFC 10008: The HTTP Query Method
IETF 发布 RFC 10008,为 HTTP 新增 QUERY 方法,用于携带请求体发送查询而无需用 GET 拼长 URL。示例中客户端以 application/x-www-form-urlencoded 提交查询,服务端返回 200 及 JSON 结果;服务器可通过 OPTIONS 响应中的 Allow 字段声明是否支持该方法。
以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。
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.¶
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" in [URL]). The Content-Length fields have been omitted for brevity.¶
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 simple way to discover support for QUERY is provided by the OPTIONS (Section 9.3.7 of [HTTP]) method:¶
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.¶
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.¶
The discovery of supported media types for QUERY is possible via the Accept-Query response field (Section 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.¶
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]):¶
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
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:¶
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
The Content-Location response field received above identifies a resource holding the result for the QUERY response it appeared on:¶
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.¶
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.¶
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:¶
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:¶
If-None-Match: "42-1"
¶
would result in a 304 (Not Modified) response (Section 15.4.5 of [HTTP]).¶
Servers can send "indirect" responses (Section 2.5) using the status code 303 (See Other, Section 15.4.4 of [HTTP]).¶
Given the request at the beginning of Appendix A.4, a server might respond with:¶
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.¶
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:¶
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.¶
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:¶
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.)¶
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.¶
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
Client Resource QUERY with content Equivalent Resource (generates /xyz) 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
A.6. More Query Formats
The following examples show requests on a JSON-shaped [RFC8259] database of RFC errata.¶
The request below uses eXtensible Stylesheet Language Transformations (XSLT) to extract errata information summarized per year and the defined errata types.¶
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> </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]]), ' ')"/> </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,
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。