.png)
4 months ago
12
Appendix A. Examples
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.¶
A.1. Simple Query
A simple query with a direct response:¶
Response:¶
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:¶
Response:¶
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 could respond with a 4xx status such as 405 (Method Not Allowed, Section 15.5.6 of [HTTP]), including the Allow response field.¶
A.3. Discovery of QUERY Formats
Discovery of supported media types for QUERY is possible via the Accept-Query (Section 3) response field:¶
Response:¶
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 415 (Unsupported Media Type, Section 15.5.16 of [HTTP]) response -- to inspect the Accept (Section 12.5.1 of [HTTP]) response field:¶
A.4. Content-Location, Location, and Indirect Responses
As described in Section 2.1, 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:¶
Response:¶
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:¶
Response:¶
A.4.2. Using Location
The Location response field identifies a resource that will respond to GET with a fresh result for the QUERY response it appeared on.¶
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:¶
Assuming no change in the query result, a subsequent conditional GET request with¶
would result in a 304 response (Not Modified, Section 15.4.5 of [HTTP]).¶
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.¶
A.4.3. Indirect Responses
Servers can send "indirect" responses (Section 2.2) 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:¶
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 Appendix A.4.2.¶
A.5. More Query Formats
The following examples show requests on a JSON-shaped ([RFC8259]) database of RFC errata.¶
The request below uses XSLT ([XSLT]) to extract errata information summarized per year and the defined errata types.¶
Response:¶
Note the Accept-Query response field indicating that another query format -- JSONPath ([RFC9535]) -- is supported as well. The request below would report the identifiers of all rejected errata submitted since 2024:¶
Response:¶
