From 066061d2b3ba6bede757c837cd754279e1560d6b Mon Sep 17 00:00:00 2001 From: Julian Reschke Date: Mon, 21 Oct 2024 05:07:31 +0100 Subject: [PATCH] query: tune language about redirects, add context about Location; add examples (fixes #1916) --- draft-ietf-httpbis-safe-method-w-body.xml | 95 +++++++++++++++++------ 1 file changed, 71 insertions(+), 24 deletions(-) diff --git a/draft-ietf-httpbis-safe-method-w-body.xml b/draft-ietf-httpbis-safe-method-w-body.xml index 1241bf1e2..d9bda913c 100644 --- a/draft-ietf-httpbis-safe-method-w-body.xml +++ b/draft-ietf-httpbis-safe-method-w-body.xml @@ -178,7 +178,6 @@ q=foo&limit=10&sort=-published
- The QUERY method is used to initiate a server-side query. Unlike the HTTP GET method, which requests that a server return a @@ -190,13 +189,11 @@ q=foo&limit=10&sort=-published cannot be assumed to be a representation of the resource identified by the target URI. - 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. - QUERY requests are both safe and idempotent with regards to the resource identified by the request URI. That is, QUERY requests do not @@ -205,29 +202,23 @@ q=foo&limit=10&sort=-published resources or even create additional HTTP resources through which the response can be retrieved. - 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 . +
- A successful response to a QUERY request can include a Content-Location + Furthermore, a successful response can include a Content-Location header field (see ) 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. - 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 @@ -238,7 +229,27 @@ q=foo&limit=10&sort=-published temporary; if a future request fails, the client can retry using the original QUERY resource and the previously submitted parameters again. +
+ +
+ + In some cases, the server may choose to respond indirectly to the QUERY + request by redirecting the user agent to a different URI (see + ). 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 . + +
+
The semantics of the QUERY method change to a "conditional QUERY" if the request message includes an If-Modified-Since, If-Unmodified- @@ -249,34 +260,29 @@ q=foo&limit=10&sort=-published are evaluated against the state of the target resource itself as opposed to the collected results of the query operation. +
-
- +
The response to a QUERY method is cacheable; a cache &MAY; use it to satisfy subsequent QUERY requests as per ). - The cache key for a query (see ) &MUST; incorporate the request content. When doing so, caches &SHOULD; first normalize request content to remove semantically insignificant differences, thereby improving cache efficiency, by: -
  • Removing content encoding(s)
  • 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")
  • Normalizing based upon knowledge of the semantics of the content itself, as indicated by the request's Content-Type field.
- Note that any such normalization is performed solely for the purpose of generating a cache key; it does not change the request itself. - -
- +
@@ -339,7 +345,7 @@ Dubois, Camille, camille.dubois@example.net
-
+
A simple query with a direct response: @@ -393,7 +399,7 @@ Dubois, Camille, camille.dubois@example.net
-
+
A simple query with an Indirect Response (303 See Other): @@ -408,10 +414,10 @@ select surname, givenname, email limit 10 Response: HTTP/1.1 303 See Other -Location: http://example.org/contacts/query123 +Location: /contacts/query123 - Fetch Query Response: + Retrieval of the Query Response: GET /contacts/query123 HTTP/1.1 Host: example.org @@ -430,6 +436,46 @@ Dubois, Camille, camille.dubois@example.net
+
+ + A simple query being redirected: + +QUERY /contacts HTTP/1.1 +Host: example.org +Content-Type: example/query +Accept: text/csv + +select surname, givenname, email limit 10 + + + Response: + +HTTP/1.1 308 Moved Permanently +Location: /morecontacts + + + Redirected request: + +QUERY /morecontacts HTTP/1.1 +Host: example.org +Content-Type: example/query +Accept: text/csv + +select surname, givenname, email limit 10 + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/csv + +surname, givenname, email +Smith, John, john.smith@example.org +Jones, Sally, sally.jones@example.com +Dubois, Camille, camille.dubois@example.net + + +
@@ -575,7 +621,8 @@ Dubois, Camille, camille.dubois@example.net
    -
  • Update QUERY example to introduction ()
    • +
  • Updated language and examples about redirects and method rewriting ()
    • +
  • Add QUERY example to introduction ()
  • Update "Sensitive information in QUERY URLs" ()
  • Field registration for "Accept-Query" ()