SPARQL 1.1 Graph Store HTTP Protocol

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a Last Call Working Draft.

The end date of the Last Call review period is 29 July 2011.

Comments on this document should be sent to public-rdf-dawg-comments@w3.org, a mailing list with a public archive. Questions and comments about SPARQL that are not related to this specification, including extensions and features, can be discussed on the mailing list public-sparql-dev@w3.org, (public archive).

This document was produced by the SPARQL Working Group, which is part of the W3C Semantic Web Activity.

Change Summary

The following is a summary of the major changes made from the last publication. The term Network-manipulable Graph Store was replaced with Graph Store. Support for indirect identification of the default graph was added. The behavior of HTTP PATCH was clarified. The retrieval of service descriptions has also been clarified. The status codes expected in response to specific behavior has been expanded. The general behavior of PUT and POST has been clarified. The term 'RDF knowledge' has been replaced with 'RDF graph content.' Graph IRIs specified via query components must be absolute (support for base resolution has been removed). The specification title has been changed to 'SPARQL 1.1 Graph Store HTTP Protocol.' Examples have been made more consistent across the document and more details regarding the actual HTTP messages and responses have been added to them.

No Endorsement

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Patents

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

1 Introduction

This document describes updating and fetching RDF graph content from a Graph Store over HTTP in the REST style [REST]. In doing so, it appeals to the following interface constraints that comprise the REST architectural style:

It emphasises the following distinct concepts: RDF graph management action, the RDF graph content identified as the target of the action, the lexical form of a Request URI, the URI of a graph in an Graph Store, and the (optional) RDF delivered with the message. The first REST constraint is met by clarifying what is being identified in the HTTP requests that are supported by this protocol and providing an alternative mechanism for identifying RDF graph content where the URI of the graph cannot be directly used. The second constraint is met by specifying how representations of RDF graphs used as the message body of HTTP requests supported by this protocol manipulate the corresponding RDF graph content. The third constraint is an inherent characteristic of RDF as the framework for a Self-Describing Semantic Web

This specification relies on an intuitive interpretation of the underlying HTTP protocol semantics to determine how the RDF graphs are modified. Where the meaning of the operations are described, an SPARQL Update equivalent syntax is shown for clarity.

When this document uses the words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and RECOMMENDED, and the words appear as emphasized text, they must be interpreted as described in RFC 2119 [RFC2119].

2 Terminology

Implementations of this protocol are HTTP/1.1 servers [RFC2616] MUST interpet request messages as graph management operations on an underlying Graph Store where the subject of the operation is indicated through the use of a Graph IRI.

3 Protocol Model

This protocol specifies the semantics of HTTP operations for managing a Graph Store. In particular, it provides operations for removing, creating, and replacing RDF graph content as well as for adding RDF statements to existing RDF graph content . The interface defined here uses URIs to direct native HTTP operations to an implementation of this protocol which responds by making appropriate modifications to the underlying Graph Store. A compliant implementation of this specification SHOULD accept HTTP requests directed at its Graph Store and handle them as specified by this protocol with the exception of security considerations such as those discussed in section 7 and others (DOS attacks, etc.)

4 Graph Identification

4.1 Direct Graph Identification

We recall from [SPARQL] that IRIs for RDF graphs in SPARQL queries identify a resource, and the resource has a representation that serializes that graph (or, more precisely: by an RDF document of the graph)

Per [RFC2616], the most common usage of a Request-URI is to identify a resource on an origin server or gateway. In our example, the corresponding request URI (http://example.com/rdf-graphs/employees) is meant to identify RDF triples on the example.com server that describe employees. In addition, the request specifies the GET method, which means that a representation of these triples should be returned. In this case, the preferred representation format is application/rdf+xml

In this way, the server would route operations on a named graph in an Graph Store via its Graph IRI. However, in using a URI in this way, we are not directly identifying an RDF graph but rather the RDF graph content that is represented by an RDF document, which is a serialization of that graph. Intuitively, the set of interpetations that satisfy [RDF-MT] the RDF graph that the RDF document is a serialization of can be thought of as this RDF graph content.

The diagram illustrates this distinction. This diagram illustrates the basic kind of operation where the request URI identifies the RDF graph content being manipulated over the protocol.

4.2 Indirect Graph Identification

Despite the convenience of using the request URI to identify RDF graph content for manipulation, it is often the case that:

As discussed in [RFC3986], query components are often used to carry identifying information in the form of key / value pairs where the value is another URI. This protocol leverages this convention and provides a specific interface whereby a graph IRI can be embedded within the query component of the request URI:

In the example above, the embedded graph IRI (http://www.example.com/other/graph) is percent-encoded [RFC3986] and indirectly identifies RDF triples to manipulate. Any server that implements this protocol and receives a request URI in this form SHOULD invoke the indicated operation on the RDF graph content identified by the IRI embedded in the query component where the IRI is the result of percent-decoding the value associated with the graph key. The embedded URI MUST be an absolute URI and the server MUST respond with a 400 Bad Request if it is not. The diagram below illustrates this.

In a similar manner, a query component comprised of the string default can be used to indicate that the operation indirectly identifies the default graph in the Graph Store. So, the example above can be modified to a request for an RDF/XML document that serializes the default graph in the Graph Store:

http://www.example.com/rdf-graphs/service identifies the HTTP service that implements this protocol. In order to dispatch requests to manage named or default graphs by embedding them in the query component of the service URL, the service URL will need to be known a priori. As will be discussed later in this document, both HTTP OPTIONS and GET requests can be sent to the service and the response to such a request is a service description document

As indicated in section 3.3 of [RFC3986], the path component (of a URI) contains data, usually organized in hierarchical form, that, along with data in the non-hierarchical query component, serves to identify a resource within the scope of the URI's scheme and naming authority. So, the full request URI identifies the same RDF graph content as does the URI embedded in the query component that is managed by the authority.

5 Graph Management Operations

This section describes the use of the HTTP verbs to determine the operations performed on RDF graph content. In places where an equivalent SPARQL Update operation is given, <graph_uri> is understood to be either the request URI or the URI indirectly specified via the query component as described above. Similarly, in the case of an operation that manages the default graph, the SPARQL Update operation will not include any mention of a graph.

For operations involving an RDF payload (PUT and POST), the server MUST parse the RDF payload according to media type specified in the Content-Type header (if provided in the request). If this header is not provided, the server SHOULD attempt to parse the RDF payload as RDF/XML. Similarly, if the Accept header is not provided, the server SHOULD return an RDF XML document.

Developers of implementations of this protocol should refer to [RFC2616] for additional details of appropriate behavior beyond those specified here. Section 5 only serves to define the behavior specific to the manipulation af RDF graph content. For example, conditional requests that make use of headers such as If-Modified-Since that are intended to reduce unnecessary network usage should be handled appropriately by implementations of this protocol per [RFC2616].

5.1 Status Codes

In response to requests to the graph management operations specified in this protocol, implementations MUST include a status code [RFC2616] appropriate for the operation indicated and the result from invoking the operation. For example, in response to operations involving a RDF payload, if the attempt to parse the RDF payload according to the provided Content-Type fails then the server should respond with a 400 Bad Request.

A request using an unsupported HTTP verb in conjunction with a malformed or unsupported request syntax should recieve a response with a 405 Method Not Allowed. If the RDF graph content identified in the request does not exist in the server, and the operation requires that it does, a 404 Not Found response code SHOULD be provided in the response.

5.2 HTTP PUT

A request that uses the HTTP PUT method SHOULD store the enclosed RDF payload as RDF graph content. In the examples below, the initial HTTP request SHOULD be understood to have the same effect as the sequence of SPARQL Update operations that follow

In the case where the default graph is targeted (via default query component) for management, the following operations are equivalent

Either the request or the encoded URI (embedded in the query component) identifies the RDF payload enclosed with the request as RDF graph content. The server MUST NOT attempt to apply the request to some other resource. If the identified RDF graph content already exists, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the identified RDF graph content does not exist and that URI is capable of being defined as new RDF graph content by the requesting user agent, the origin server SHOULD create the RDF graph content with that URI in the underlying Graph Store. DROP is needed to remove any previous RDF graph content. Developers should refer to [SPARQL-UPDATE] for the specifics of how to handle empty graphs. In particular, if the request body is empty and there is sufficient authorization to create a new named graph with an IRI of that indicated by the request URI, then an empty graph would need to be created.

If new RDF graph content is created, the origin server MUST inform the user agent via the 201 Created response. If existing RDF graph content is modified, either the 200 OK or 204 No Content response codes SHOULD be sent to indicate successful completion of the request. If the resource could not be created or modified with the Request-URI (perhaps due to security considerations), an appropriate error response SHOULD be given that reflects the nature of the problem.

5.3 HTTP DELETE

A request that uses the HTTP DELETE method SHOULD delete the RDF graph content identified by either the request or encoded URI. This method MAY be overridden by human intervention (or other means) on the origin server. If there is no such RDF graph content in the Graph Store, the server MUST respond with a 404 Not Found response code.

in the case where a named graph is targeted for management. Otherwise, the following

A response code of 200 OK or 204 No Content SHOULD be given in the response if the operation succeeded or 202 (Accepted) if the action has not yet been enacted. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the RDF graph content or move it to an inaccessible location. In the event the operation is overridden, a response code of 403 Forbidden should be returned.

5.4 HTTP POST

A request that uses the HTTP POST method SHOULD be understood as a request that the origin server perform an RDF merge of the enclosed RDF payload enclosed into the RDF graph content identified by the request or encoded URI. The following two operations are considered to have the same effect

In the case where a default graph is targeted for management, the following are equivalent

If the request URI identifies the underlying Graph Store, the origin server SHOULD create a new RDF graph comprised of the statements in the RDF payload and return a designated graph IRI associated with the new graph. The new graph IRI should be specified in the Location HTTP header along with a 201 Created code and be different from the request URI. Within a service description document for an implementation of this protocol, the URI of an instance of the sd:Dataset class is understood to be the identifier of the Graph Store

5.5 HTTP GET

A request that uses the HTTP GET method SHOULD retrieve an RDF payload that is a serialization of the named graph paired with the graph IRI in the Graph Store.

Where the request involves the default query component, the following two operations are equivalent

The response to such a SHOULD be made cacheable wherever possible and in any of the preferred representation formats specified in the Accept request-header field. In the event that the specified representation format is not supported, a 406 Not Acceptable response code should be returned.

5.5.1 Ambiguity Regarding the Range of HTTP GET (Informative)

Historically, there has been some ambiguity regarding the nature of what is returned from dereferencing a URI. When an HTTP GET is invoked with a request URI, what is returned and what is its relation to the resource identified by the request URI? In resolving this ambiguity, the W3C Technical Architecture Group specified a simple rule that determines the nature of the resource based on the response code returned. In this protocol, HTTP GET requests are used to retrieve a representation of the RDF graph content identified (directly or indirectly) by the Request-URI. Graph IRIs identify RDF graph content (an information resource) and so such a request should recieve a response with a 200 (Ok) which is consistent with these rules, the first of which states: If an "http" resource responds to a GET request with a 2xx response, then the resource identified by that URI is an information resource;

Information resources are resources with essential characteristics that can all be conveyed in a message [WEBARCH]. In this case, the characteristics of RDF graph content can be conveyed as RDF payload which serializes the named graph paired with the graph IRI in the underlying Graph Store. This protocol provides a means for requesting the representation without the need for indirection at the protocol level even if the naming authority associated with the URI of the named RDF graph in the Graph Store is not the same as the server managing the identified RDF graph content.

5.6 HTTP HEAD

When used in this protocol, the HTTP HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. It is meant to be used for testing dereferencable URIs for validity, accessibility, and recent modification. The response to such a request from a server that manages a Graph Store MAY be cacheable. If the new field values indicate that the cached RDF graph content differs from the current entity (as would be indicated by a change in Content-Length, Content-MD5, ETag or Last-Modified), then the cache MUST treat the cache entry as stale.

5.7 HTTP PATCH (Informative)

The IETF specified Patch Method for HTTP can be used to request that a set of changes described in the request entity be applied to the named graph associated with the graph IRI of the RDF graph content resource identified by the Request-URI.

SPARQL 1.1 Update is RECOMMENDED for use as a patch document. In particular, SPARQL 1.1 Update requests that manage the graph associated with the RDF graph content identified (directly or indirectly) in the request can be used as the RDF payload of a HTTP PATCH request to modify it. If a SPARQL 1.1 Update request is used as the RDF payload for a PATCH request that makes changes to more than one graph or the graph it modifies is not the one indicated, it is RECOMMENDED that the server respond with a 422 Unprocessable Entity status. Such a request would be counter to the intuition that "REST uses a resource identifier to identify the particular resource involved in an interaction between components." [REST]

Intuitively, the difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the RDF graph content given by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the RDF graph content stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how the RDF graph content residing on the origin server should be modified to produce a new version.

5.8 Graph Store Service Discovery (Informative)

It is RECOMMENDED that the OPTIONS and GET methods be used in a request whose URI identifies the service that implements this protocol in order to retrieve information about the features of the service. Per section 2 of SPARQL 1.1 Service Descriptions, it is RECOMMENDED that a service description document be returned from such a request, especially if the implementation also supports the SPARQL Protocol for RDF.

This can aid a web agent in the client-side creation, and use of request URIs for the discovery and augmentation of an underlying Graph store by dispatching RDF documents to its content via HTTP operations.

6 Security Considerations

As with any protocol that is implemented as a layer above HTTP, implementations SHOULD take advantage of the many security-related facilities associated with it and are not required to carry out requested graph management operations that may be in contradistinction to a particular security policy in place. For example, when faced with an unauthenticated request to replace system critical RDF statements in a graph through the PUT method, applications may consider responding with the 401 status code (Unauthorized), indicating that the appropriate authorization is required. In cases where authentication is provided fails to meet the requirements of a particular access control policy, the 403 status code (Forbidden) can be sent back to the client to indicate this failure to meet the access control policy.