QUERY: examples section (fixes #1906)

draft-ietf-httpbis-safe-method-w-body.xml

@@ -513,8 +513,252 @@ Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"</artwork>
   </references>
 
   <section title="Examples" anchor="examples">
-<!-- TODO: add Content-Length fields once examples are stable -->
     <t>
+      The examples below are for illustrative purposes only; if one needs to
+      send queries that are actually this short, it is probably better to use GET.
+    </t>
+    <t>
+      The media type used in most examples is "application/x-www-form-urlencoded"
+      (as used in POST requests from browser user clients).
+      The Content-Length fields have been omitted for brevity.
+    </t>
+
+    <section title="Simple Query" anchor="example.simple">
+      <t>A simple query with a direct response:</t>
+<artwork type="http-message">
+QUERY /contacts HTTP/1.1
+Host: example.org
+Content-Type: application/x-www-form-urlencoded
+Accept: application/json
+
+select=surname,givenname,email&amp;limit=10&amp;match=%22email=*@example.*%22
+</artwork>
+
+      <t>Response:</t>
+<artwork type="http-message">
+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" }
+]
+</artwork>
+    </section>
+
+    <section title="Discovery of QUERY support" anchor="example.discovery.method">
+      <t>
+        A simple way to discover support for QUERY is provided by the OPTIONS
+        (<xref target="HTTP" section="9.3.7"/>) method:
+      </t>
+
+<artwork type="http-message">
+OPTIONS /contacts HTTP/1.1
+Host: example.org
+
+</artwork>
+
+      <t>Response:</t>
+<artwork type="http-message">
+HTTP/1.1 200 OK
+
+Allow: GET, QUERY, OPTIONS, HEAD
+</artwork>
+      <t>
+        The Allow response field (<xref target="HTTP" section="10.2.1"/>) denotes the set of
+        supported methods on the specified resource.
+      </t>
+      <t>
+        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 could respond with an 4xx status such as 405 ("Method Not Allowed",
+        <xref target="HTTP" section="15.5.6"/>), including the Allow response field.
+      </t>
+    </section>
+
+    <section title="Discovery of QUERY Formats" anchor="example.discovery.formats">
+      <t>
+        Discovery of supported media types for QUERY is possible via the Accept-Query
+        (<xref target="field.accept-query"/>) response field:
+      </t>
+
+<artwork type="http-message">
+  HEAD /contacts HTTP/1.1
+  Host: example.org
+
+</artwork>
+
+<t>Response:</t>
+<artwork type="http-message">
+  HTTP/1.1 200 OK
+  Content-Type: application/xhtml
+  Accept-Query: application/x-www-form-urlencoded, application/sql
+</artwork>
+      <t>
+        Responses to which request methods will contain Accept-Query will depend on
+        the resource being accessed.
+      </t>
+      <t>
+        An alternative to checking Accept-Query would be to make a QUERY request, and then
+        - in case of a 4xx status such as 415 ("Unsupported Media Type", <xref target="HTTP" section="12.5.1"/>) response -
+        to inspect the Allow (<xref target="HTTP" section="15.5.16"/>) response field:
+      </t>
+<artwork type="http-message">
+  HTTP/1.1 415 Unsupported Media Type
+  Content-Type: application/xhtml
+  Accept: application/x-www-form-urlencoded, application/sql
+</artwork>
+    </section>
+
+    <section title="Content-Location, Location, and Indirect Responses" anchor="example.content-location.location.indirect">
+      <t>
+        The Content-Location and Location response fields 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 for the same request. Going back to the example from <xref target="example.simple"/>:
+      </t>
+<artwork type="http-message">
+QUERY /contacts HTTP/1.1
+Host: example.org
+Content-Type: application/x-www-form-urlencoded
+Accept: application/json
+
+select=surname,givenname,email&amp;limit=10&amp;match=%22email=*@example.*%22
+</artwork>
+        <t>Response:</t>
+<artwork type="http-message">
+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 November 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" }
+]
+</artwork>
+
+      <section title="Using Content-Location" anchor="example.content-location">
+        <t>
+          The Content-Location response field received above identifies a resource holding
+          the result for the QUERY response it appeared on:
+        </t>
+<artwork type="http-message">
+GET /contacts/stored-results/17
+Host: example.org
+Accept: application/json
+
+</artwork>
+        <t>Response:</t>
+<artwork type="http-message">
+HTTP/1.1 200 OK
+Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
+Date: Sun, 17 November 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" }
+]
+</artwork>
+      </section>
+
+      <section title="Using Location" anchor="example.location">
+        <t>
+          The Location response field identifies a resource that will respond to GET
+          with a fresh result for the QUERY response it appeared on.
+        </t>
+<artwork type="http-message">
+GET /contacts/stored-queries/42
+Host: example.org
+Accept: application/json
+
+</artwork>
+        <t>
+          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:
+        </t>
+<artwork type="http-message">
+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 November 2024, 16:13:17 GMT
+
+[
+  { "surname": "Smith",
+    "givenname": "John",
+    "email": "smith@example.org" },
+  { "surname": "Dubois",
+    "givenname": "Camille",
+    "email": "camille.dubois@example.net" }
+]
+</artwork>
+        <t>
+          Assuming no change in the query result, a subsequent conditional GET request with
+        </t>
+<artwork type="http-message">
+If-Non-Match: "42-1"
+</artwork>
+        <t>
+          would result in a 304 response ("Not Modified", <xref target="HTTP" section="15.4.5"/>).
+        </t>
+        <t>
+          Note that there's 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.
+        </t>
+      </section>
+
+      <section title="Indirect Responses" anchor="example.indirect">
+        <t>
+          Servers can send "indirect" responses using the status code 303 ("See Other",
+          <xref target="HTTP" section="15.4.4"/>).
+        </t>
+        <t>
+          Given the request at the beginning of <xref target="example.content-location.location.indirect"/>,
+          a server might respond with:
+        </t>
+<artwork type="http-message">
+HTTP/1.1 303 See Other
+Content-Type: text/plain
+Date: Sun, 17 November 2024, 16:13:17 GMT
+Location: /contacts/stored-queries/42
+
+See stored query at "/contacts/stored-queries/42".
+</artwork>
+        <t>
+          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 an alternative
+          resource. This resource could then be used as shown in
+          <xref target="example.location"/>.
+        </t>
+      </section>
+
+    </section>
+
+    <!--    <t>
       The non-normative examples in this section make use of a simple,
       hypothetical plain-text based query syntax based on SQL with results
       returned as comma-separated values. This is done for illustration
@@ -677,7 +921,7 @@ Jones, Sally, sally.jones@example.com
 Dubois, Camille, camille.dubois@example.net
 </artwork>
 
-    </section>
+    </section>-->
   </section>
 
 <section title="Change Log" anchor="change.log" removeInRFC="true">
@@ -743,6 +987,7 @@ Dubois, Camille, camille.dubois@example.net
 </section>
 <section title="Since draft-ietf-httpbis-safe-method-w-body-07" anchor="changes.since.07">
 <ul>
+  <li>Examples Section revised (<eref target="https://github.com/httpwg/http-extensions/issues/1906"/>)</li>
   <li>Discuss Range Requests (<eref target="https://github.com/httpwg/http-extensions/issues/2979"/>)</li>
 </ul>
 </section>