Proposal for HTTP QUERY Verb
- 1 Introduction
- 2 Running a Query
- 3 Persisting Queries
- 4 Running a Stored Query
- 5 Discovering Capabilities
- 6 Header Fields
This is a proposal for a new HTTP verb: QUERY. It is inspired by RFC 5323 which defines WebDAV Search, although the details are significantly different. The search or query (we use the words interchangeably in this document) specification is in the body of the QUERY request. The query searches the Resource URL on which the request is made. If the query succeeds, the results are contained in the body of response.
QUERY (return selected parts of the resource) is related to GET as PATCH – RFC 5789-- (update selected parts of the resource) is to PUT In some sense it can be looked at as a GET with a body, where the body contains the selection information.
- We need a mechanism to query and return parts of complex resources such as RDF graphs, LDP collections etc. Query parameters are inadequate to express the complexity of the queries required. Also, the query may often exceed the maximum length of the Request-URI allowed in HTTP requests.
- If you use query parameters, attribute names become part of the Request-URI. This can be a security exposure as the URI is available to intermediaries while the body is not.
2 Running a Query
The client makes a HTTP QUERY request to initiate a server-side search. The body of the request contains the query specification. The query may be specified using several different grammars. The media-type of the specification MUST be indicated in the content-type header of the request.
If the response is requested in a specific format, Accept headers can be used to indicate the type of response.
If the query succeeds, a 200 OK response is returned. Other HTTP response codes can be returned in other circumstances. For example a 400 would be returned if the query was syntactically incorrect.
QUERY is a safe method. It does not modify the resource and has no effects other executing the query and returning the results. See RFC 2616 Section 9.1.1. It is also idempotent. See RFC 2616 Section 9.1.2.
The results of a QUERY request can be cached. Thus, if the same query is executed on the same resource the results can be served from the cache as long as the underlying resource has not changed. Cache control headers and ETag headers can be used with the QUERY request as appropriate
3 Persisting Queries
Queries can be stored on the server using a PUT, modified using a POST or PATCH and deleted using a DELETE.
4 Running a Stored Query
To execute a stored query, the URL of the stored query can be contained in the body of the request or in a link header with rel = “query”. Alternately, you do a GET on the URL of the query concatenated with “/results”. This will return the query result either by re-evaluating the query or by serving it from the cache.
Stored queries can be parameterized. If the query is a parameterized query, then appropriate query parameters must be supplied in the request URL query string. For example, if the query requires two parameters, the query string in the request may be of the form “?var1=value1&var2=value2”.
If fewer values are supplied in the query string than there are parameters in the query, a 400 Malformed Request would be returned. Excess values in query string would be ignored. If the parameter names in the query string do not match the names in the query, 400 would be returned. Similarly, if the datatypes of the values in the query string do not match the datatypes expected for the query variables a 400 would be returned.
5 Discovering Capabilities
Clients can determine whether a server supports the QUERY method by making an OPTIONS request on the server URL or a dataURL. This is a normal invocation of OPTIONS as defined in Section 9.2 of [RFC2616]. If QUERY is supported, the server MUST list QUERY in the Allow header defined in Section 14.7 of [RFC2616]. Servers supporting QUERY must also include the QUERY header in the OPTIONS response. This header identifies metadata for the search grammars supported by the resource. The value is a non-empty list of URLs that indicate the metadata for the supported grammars.
6 Header Fields
6.1 Request Header Fields
Indicates the media-type of the search specification
Indicates the format of the response
6.1.3 cacheable flag (optional, default=false)
To indicate whether or not to cache results between multiple query executions. If enabled, query results will return an ETag that client can use between query execution requests.
Indicates the location of a stored query. .
Other HTTP request headers have their usual meanings.
6.2 Response Header Fields
If the server supports the SEARCH verb then SEARCH must be included in the Allow header in response to a OPTIONS request
If the server supports the SEARCH verb then response to an OPTIONS request must include a non-empty Search header listing the URLs of the metadata for the query syntaxes supported.
Other HTTP response headers have their usual meanings.