1. HTTP (Hypertext Transfer Protocol)

  1. Queries in HTTP
    1. GET requests
    2. POST requests (redirect version)
    3. POST requests (safe version)
    4. REPORT requests
    5. SEARCH requests
    6. Examples
      1. SPARQL

Queries in HTTP

Typically in HTTP, a client downloads resources, and processes them locally. The query resource paradigm instead allows a client to submit a query, which is processed on the server side, returning results in the response body. The resource that processes the query is called an endpoint. Query endpoints are typically used when the data set that must be computed is truly massive, or if the query is very complicated and too long to fit into a URI.

A single HTTP endpoint may choose to implement all of the below solutions, or just one.

GET requests

For short queries that do fit in the request URI, query resources should support GET requests that allow query parameters added to the endpoint URI.

For example, if the endpoint is http://example.com/foo, then the resource representing the query results could be http://example.com/foo?q={query}. The name of the parameter is arbitrary, but q is short and common. The parameter name can be omitted entirely: http://example.com/foo?{query} is also acceptable, but this is not compatible with HTML forms.

A GET request to the query resource (without a provided query) must describe the syntax with a URI Template or an HTML form. The response should also include a description of the data that will be queried over, and the query syntax.

POST requests (redirect version)

This version is most friendly to Web browsers. Follow the typical POST behavior: create a new resource, then perform a 303 (See Other) redirect to that resource. A 201 (Created) or 200 (OK) response would also be acceptable (depending on if the resource was created or not), but See Other is more compatible with Web browsers without losing significant functionality.

The best URI to mint is a content-addressable resource, one based on the contents of the query, so that a potential attacker would have to know the query in order to predict the URI being created. A simple hash of the query contents should suffice:

POST /query HTTP/1.1
Content-Type: application/json

{ "id": { "$gt": 200 } }
HTTP/1.1 303 See Other
Location: /query/01ba4719c80b6fe911b091a7c0

The resource may be deleted once it has been read by the client; or it may be cleaned out some time after as part of a normal cache clearing process.

Queries may also be retained indefinitely, like more traditional POST requests that create a resource, and treated as first-class resources that can be shared amongst users. They may then be deleted by the user when no longer necessary.

The server should keep a distinction between the resource that is the query, and the resource that is the query results. If the server needs to make the text of the original query available, it should be provided as a separate resource, linked to and from the query results resource.

To support HTML forms, servers should also support Content-Type: application/x-www-urlencoded requests, accepting the same syntax seen in the query component of a GET request.

POST requests (safe version)

This form is the same as the REPORT method below, but uses POST instead. It is intended for workflows where the client or server do not support the REPORT method, but must use a similar workflow. For use in Web browsers, the redirect version (above) is preferred.

For servers supporting both the redirect and safe variants, servers may use a Prefer request-header to specify the behavior to use.

REPORT requests

Main article: REPORT method

REPORT is an "extensible mechanism for obtaining information about a resource". When using this method, simply upload the query as the request-body.

SEARCH requests

This method is similar to REPORT: you simply upload the query as the request-body. This method is specifically defined to run a query over a set of resources, but it requires a WebDAV multi-status response.

Examples

SPARQL

This is the media type for SPARQL queries, usage is described in SPARQL 1.1 Protocol.