Skip to content

Commit

Permalink
query: tune language about redirects, add context about Location; add…
Browse files Browse the repository at this point in the history 
… examples (fixes #1916)
  • Loading branch information
@reschke
reschke committed Oct 21, 2024
1 parent a2332a5 commit 066061d
Showing 1 changed file with 71 additions and 24 deletions.
95 changes: 71 additions & 24 deletions draft-ietf-httpbis-safe-method-w-body.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,6 @@ q=foo&limit=10&sort=-published
</section>

<section title="QUERY" anchor="query">

<t>
The QUERY method is used to initiate a server-side query. Unlike
the HTTP GET method, which requests that a server return a
Expand All @@ -190,13 +189,11 @@ q=foo&amp;limit=10&amp;sort=-published
cannot be assumed to be a representation of the resource identified by
the target URI.
</t>

<t>
The content of the request defines the query. Implementations &MAY; use
a request content of any media type with the QUERY method, provided that it
has appropriate query semantics.
</t>

<t>
QUERY requests are both safe and idempotent with regards to the
resource identified by the request URI. That is, QUERY requests do not
Expand All @@ -205,29 +202,23 @@ q=foo&amp;limit=10&amp;sort=-published
resources or even create additional HTTP resources through which the
response can be retrieved.
</t>

<t>
A successful response to a QUERY request is expected to provide some
indication as to the final disposition of the operation. For
instance, a successful query that yields no results can be represented
by a 204 No Content response. If the response includes content,
it is expected to describe the results of the operation.
In some cases, the server may choose to respond indirectly to the QUERY
request by returning a 3xx Redirection with a Location header field specifying
an alternate Request URI from which the results can be retrieved
using an HTTP GET request. Various non-normative examples of successful
QUERY responses are illustrated in <xref target="examples" />.
</t>

<section title="Content-Location and Location Fields" anchor="location">
<t>
A successful response to a QUERY request can include a Content-Location
Furthermore, a successful response can include a Content-Location
header field (see <xref target="HTTP" section="8.7"/>) containing an
identifier for a resource corresponding to the results of the
operation. 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.
</t>

<t>
A server &MAY; create or locate a resource that identifies the query
operation for future use. If the server does so, the URI of the resource
Expand All @@ -238,7 +229,27 @@ q=foo&amp;limit=10&amp;sort=-published
temporary; if a future request fails, the client can retry using the
original QUERY resource and the previously submitted parameters again.
</t>
</section>

<section title="Redirection" anchor="redirection">
<t>
In some cases, the server may choose to respond indirectly to the QUERY
request by redirecting the user agent to a different URI (see
<xref target="HTTP" section="15.4"/>). The semantics of the redirect
response do not differ from other methods. For instance, a 303 (See Other)
response would indicate that the Location field identifies an
alternate URI from which the results can be retrieved
using a GET request (this use case is also covered by the
use of the Location response field in a 2xx response).
On the other hand, response codes 307 (Temporary Redirect) and 308
(Permanent Redirect) can be used to request the user agent to redo
the QUERY request on the URI specified by the Location field.
Various non-normative examples of successful
QUERY responses are illustrated in <xref target="examples" />.
</t>
</section>

<section title="Conditional Requests" anchor="conditional">
<t>
The semantics of the QUERY method change to a "conditional QUERY" if
the request message includes an If-Modified-Since, If-Unmodified-
Expand All @@ -249,34 +260,29 @@ q=foo&amp;limit=10&amp;sort=-published
are evaluated against the state of the target resource itself as opposed
to the collected results of the query operation.
</t>
</section>

<section title="Caching">

<section title="Caching" anchor="caching">
<t>
The response to a QUERY method is cacheable; a cache &MAY; use it to satisfy subsequent
QUERY requests as per <xref target="HTTP-CACHING" section="4"/>).
</t>

<t>
The cache key for a query (see <xref target="HTTP-CACHING" section="2"/>) &MUST;
incorporate the request content. When doing so, caches &SHOULD; first normalize request
content to remove semantically insignificant differences, thereby improving cache
efficiency, by:
</t>

<ul>
<li>Removing content encoding(s)</li>
<li>Normalizing based upon knowledge of format conventions, as indicated by the any media type suffix in the request's Content-Type field (e.g., "+json")</li>
<li>Normalizing based upon knowledge of the semantics of the content itself, as indicated by the request's Content-Type field.</li>
</ul>

<t>
Note that any such normalization is performed solely for the purpose of generating a cache key; it
does not change the request itself.
</t>

</section>

</section>
</section>

<section title="The &quot;Accept-Query&quot; Header Field" anchor="field.accept-query">
Expand Down Expand Up @@ -339,7 +345,7 @@ Dubois, Camille, [email protected]

</section>

<section title="Simple QUERY with a Direct Response and Location fields">
<section title="Simple QUERY with a Direct Response and Location Fields">

<t>A simple query with a direct response:</t>
<artwork type="http-message">
Expand Down Expand Up @@ -393,7 +399,7 @@ Dubois, Camille, [email protected]

</section>

<section title="Simple QUERY with indirect response (303 See Other)">
<section title="Simple QUERY with Indirect Response (303 See Other)">

<t>A simple query with an Indirect Response (303 See Other):</t>
<artwork type="http-message">
Expand All @@ -408,10 +414,10 @@ select surname, givenname, email limit 10
<t>Response:</t>
<artwork type="http-message">
HTTP/1.1 303 See Other
Location: http://example.org/contacts/query123
Location: /contacts/query123
</artwork>

<t>Fetch Query Response:</t>
<t>Retrieval of the Query Response:</t>
<artwork type="http-message">
GET /contacts/query123 HTTP/1.1
Host: example.org
Expand All @@ -430,6 +436,46 @@ Dubois, Camille, [email protected]

</section>

<section title="Simple QUERY with Redirect Response (308 Moved Permanently)">

<t>A simple query being redirected:</t>
<artwork type="http-message">
QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 10
</artwork>

<t>Response:</t>
<artwork type="http-message">
HTTP/1.1 308 Moved Permanently
Location: /morecontacts
</artwork>

<t>Redirected request:</t>
<artwork type="http-message">
QUERY /morecontacts HTTP/1.1
Host: example.org
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 10
</artwork>

<t>Response:</t>
<artwork type="http-message">
HTTP/1.1 200 OK
Content-Type: text/csv

surname, givenname, email
Smith, John, [email protected]
Jones, Sally, [email protected]
Dubois, Camille, [email protected]
</artwork>

</section>
</section>

<section title="Security Considerations">
Expand Down Expand Up @@ -575,7 +621,8 @@ Dubois, Camille, [email protected]
</section>
<section title="Since draft-ietf-httpbis-safe-method-w-body-05" anchor="changes.since.05">
<ul>
<li>Update QUERY example to introduction (<eref target="https://github.com/httpwg/http-extensions/issues/2171"/>)</li>
<li>Updated language and examples about redirects and method rewriting (<eref target="https://github.com/httpwg/http-extensions/issues/1917"/>)</li>
<li>Add QUERY example to introduction (<eref target="https://github.com/httpwg/http-extensions/issues/2171"/>)</li>
<li>Update "Sensitive information in QUERY URLs" (<eref target="https://github.com/httpwg/http-extensions/issues/2853"/>)</li>
<li>Field registration for "Accept-Query" (<eref target="https://github.com/httpwg/http-extensions/issues/2903"/>)</li>
</ul>
Expand Down

0 comments on commit 066061d

Please sign in to comment.