SPARQL 1.1 Graph Store HTTP Protocol /**/ pre.data { border: thin solid #88AA88; background-color: #E8F0E8; margin: 1em 4em 1em 0em ; } .wgNote { border: 0.2em solid red; padding: 0.5em ; margin: 1em 4em 1em 2em ; }
/**/ SPARQL 1.1 Graph Store HTTP Protocol W3C Recommendation 21 March 2013 This version: http://www.w3.org/TR/2013/REC-sparql11-http-rdf-update-20130321/ Latest version: http://www.w3.org/TR/sparql11-http-rdf-update/ Previous version: http://www.w3.org/TR/2013/PR-sparql11-http-rdf-update-20130129/ Editor: Chimezie Ogbuji, [email protected] Please refer to the errata See also translations Copyright W3C ® MIT ERCIM Keio Beihang liability trademark document use Abstract This document describes the use of HTTP operations for the purpose of managing a collection of RDF graphs. This interface is an alternative to the SPARQL 1.1 Update protocol. Most of the operations defined here can be performed using that interface, but for some clients or servers, this interface may be easier to implement or work with. This specification may serve as a non-normative suggestion for HTTP operations on RDF graphs which are managed outside of a SPARQL 1.1 graph store. Status of This Document May Be Superseded 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 Set of Documents This document is one of eleven SPARQL 1.1 Recommendations produced by the SPARQL Working Group SPARQL 1.1 Overview SPARQL 1.1 Query Language SPARQL 1.1 Update SPARQL1.1 Service Description SPARQL 1.1 Federated Query SPARQL 1.1 Query Results JSON Format SPARQL 1.1 Query Results CSV and TSV Formats SPARQL Query Results XML Format (Second Edition) SPARQL 1.1 Entailment Regimes SPARQL 1.1 Protocol SPARQL 1.1 Graph Store HTTP Protocol No Substantive Changes There have been no substantive changes to this document since the previous version change log color-coded diff Please Send Comments Please send any comments to [email protected] public archive SPARQL Working Group errata [email protected] public archive Endorsed By W3C This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web. Patents This document was produced by a group operating under the 5 February 2004 W3C Patent Policy public list of any patent disclosures Essential Claim(s) section 6 of the W3C Patent Policy Table of Contents Introduction Terminology Protocol Model Graph Identification 4.1 Direct Graph Identification 4.2 Indirect Graph Identification Graph Management Operations 5.1 Status Codes 5.2 HTTP GET 5.2.1 Ambiguity Regarding the Range of HTTP GET (Informative) 5.3 HTTP PUT 5.4 HTTP DELETE 5.5 HTTP POST 5.6 HTTP HEAD 5.7 HTTP PATCH (Informative) Security Considerations References Appendix 8.1 Acknowledgements 1 Introduction This document describes an application protocol for the distributed updating and fetching of RDF graph content in a Graph Store via the mechanics of the Hypertext Transfer Protocol (HTTP) [RFC2616] identification of resources (via Request IRI and the IRI of a graph in a Graph Store) manipulation of resources through representations (via the use of an RDF graph representation as input to RDF graph management actions) self-describing messages (via the inherent characteristics 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 interaction with a Graph Store. Where the meaning of the operations are described, a SPARQL Update equivalent syntax is shown for clarity. When this document uses the words MUST MUST NOT SHOULD SHOULD NOT MAY RECOMMENDED RFC 2119 [RFC2119] 2 Terminology The following terminology is used in this document: URI [RFC3986] IRI [RFC3987] Resource [RDF-MT] [RFC2616] Resolvable URI GET [WEBARCH] RDF document Graph Store [SPARQL-UPDATE] Graph IRI RDF graph content [WEBARCH] RDF payload [RFC2616] Servers implementing this protocol are HTTP/1.1 servers [RFC2616] 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 IRIs 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 MUST 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 (Denial-of-Service attacks, etc.) 4 Graph Identification A client using this protocol to manipulate a graph store needs an IRI for each graph. Within the graph store, each graph (except the default graph) is associated with a graph IRI. In some cases ("Direct Graph Identification"), the graph IRIs can be directly used as the request URI of a graph management operation. In other cases ("Indirect Graph Identification"), the Graph Store IRI is used to route the operations onto RDF graph content. 4.1 Direct Graph Identification We recall from [SPARQL] Consider the following HTTP request to a server that implements this protocol: GET /rdf-graphs/employees HTTP/1.1 Host: example.com Accept: text/turtle; charset=utf-8 Per [RFC2616] http://example.com/rdf-graphs/employees GET text/turtle In this way, the server would route operations onto a named graph directly [RDF-MT] serializes 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. Requests to an implementation of this protocol receive HTTP requests using one of the HTTP methods that is directed at some RDF graph content. Above the arrows indicating the request is the relevant HTTP methods and below is any message body content or additional headers that accompany the request. At the head of the arrows leaving RDF graph content is the message body for the corresponding response. Figure 1 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: the naming authority associated with the IRI of an RDF graph in a Graph Store is not the same as the server managing the identified RDF content the naming authority is not available the IRI is not dereferenceable As discussed in [RFC3986] GET /rdf-graph-store? graph http%3A//www.example.com/other/graph In the example above, the encoded graph IRI ( http://www.example.com/other/graph [RFC3986] indirectly graph 400 Bad Request Figure 2 As indicated in section 3.3 [RFC3986] A future Working Group may provide additional interfaces for indirectly identifying RDF graph content as well as mechanisms for their discovery. In a similar manner, a query component comprised of the string default GET /rdf-graph-store? default In a request such as: GET /rdf-graph-store? graph http%3A//www.example.com/other/graph http://www.example.com/rdf-graph-store 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 IRI or the IRI 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. If the Accept Content-Type This protocol also supports the proper handling of operations involving "multipart/form-data" [html4] 17.13.4 Form content types multipart/form-data 5.5 Developers of implementations of this protocol should refer to [RFC2616] [RFC2616] 5.1 Status Codes Implementations MUST use the response status codes defined in HTTP [RFC2616] Content-Type 400 Bad Request A request using an unsupported HTTP verb in conjunction with a malformed or unsupported request syntax MUST receive a response with a 405 Method Not Allowed 404 Not Found If a clients issues a POST or PUT with a content type that is not understood by the graph store, the implementation MUST respond with 415 Unsupported Media Type 5.2 HTTP GET A request that uses the HTTP GET [RFC2616] The following two operations are considered to be equivalent GET /rdf-graph-store?graph=..graph_uri.. HTTP/1.1 Host: example.com Accept: text/turtle; charset=utf-8 CONSTRUCT { ?s ?p ?o } WHERE { GRAPH <graph_uri> { ?s ?p ?o } } Where the request involves the default GET /rdf-graph-store?default HTTP/1.1 Host: example.com Accept: text/turtle; charset=utf-8 CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o } The response to such request 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 5.2.1 Ambiguity Regarding the Range of HTTP GET (Informative) Historically, there has been some ambiguity GET simple rule GET 200 (Ok) If an "http" resource responds to a GET 2xx Information resources are resources with essential characteristics that can all be conveyed in a message [WEBARCH] 5.3 HTTP PUT A request that uses the HTTP PUT PUT /rdf-graph-store?graph=..graph_uri.. HTTP/1.1 Host: example.com Content-Type: text/turtle ... RDF payload ... DROP SILENT GRAPH <graph_uri>; INSERT DATA { GRAPH <graph_uri> { .. RDF payload .. } } In the case where the default graph is targeted (via default PUT /rdf-graph-store?default HTTP/1.1 Host: example.com Content-Type: text/turtle ... RDF payload ... DROP SILENT DEFAULT; INSERT DATA { .. RDF payload .. } Either the request or the encoded IRI (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 MUST 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 IRI is capable of being defined as new RDF graph content by the requesting user agent, the origin server MUST create the RDF graph content with that IRI in the underlying Graph Store. DROP [SPARQL-UPDATE] 400 Bad Request If new RDF graph content is created, the origin server MUST inform the user agent via the 201 Created 200 OK 204 No Content 5.4 HTTP DELETE A request that uses the HTTP DELETE 404 Not Found DELETE /rdf-graph-store?graph=..graph_uri.. HTTP/1.1 Host: example.com Is equivalent to: DROP GRAPH <graph_uri> in the case where a named graph is targeted for management. Otherwise, the following DELETE /rdf-graph-store?default HTTP/1.1 Host: example.com is equivalent to DROP DEFAULT A response code of 200 OK 204 No Content 202 (Accepted) 403 Forbidden 5.5 HTTP POST A request that uses the HTTP POST POST /rdf-graph-store?graph=..graph_uri.. HTTP/1.1 Host: example.com Content-Type: text/turtle ... RDF payload ... INSERT DATA { GRAPH <graph_uri> { .. RDF payload .. } } In the case where a default graph is targeted for management, the following are equivalent POST /rdf-graph-store?default HTTP/1.1 Host: example.com Content-Type: text/turtle ... RDF payload ... INSERT DATA { .. RDF payload .. } As mentioned earlier, "multipart/form-data" can be dispatched to implementations of this protocol. When used with POST this operation MUST be understood as a request that the origin server perform an RDF merge of the graphs - that the documents submitted with the multipart form are a serialization of - into the RDF graph content identified by the request or encoded IRI. In such a case, if the Content-Type 400 Bad Request If the request IRI identifies the underlying Graph Store, the origin server MUST 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 This scenario is useful for situations where the requesting agent either does not want to specify the graph IRI of a new graph to create (via the PUT method) or does not have the appropriate authorization to do so. If the graph IRI does not identify either a Graph Store or RDF graph content, the origin server should respond with a 404 Not Found In either case, if the request body is empty, the implementation SHOULD respond with 204 No Content This protocol is a companion to the use of both SPARQL Update and SPARQL Query over the SPARQL protocol via HTTP POST. Both protocols specify different 5.6 HTTP HEAD When used in this protocol, the HTTP HEAD GET 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. As mentioned in the beginning of the previous section, developers should refer to [RFC2616] 5.7 HTTP PATCH The IETF specified Patch Method for HTTP SPARQL 1.1 Update can be used 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 would be prudent for the server to respond with a 422 Unprocessable Entity 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 IRI. 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. 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) 403 status code (Forbidden) 7 References 7.1 RFC2119 RFC 2119: Key words for use in RFCs to Indicate Requirement Levels HTML 4.01 HTML 4.01 Specification RFC3986 Uniform Resource Identifier (URI): Generic Syntax RFC2616 Hypertext Transfer Protocol - HTTP/1.1 WEBARCH Architecture of the World Wide Web, Volume One Latest version RFC3987 Internationalized Resource Identifiers (IRIs) SPARQL-UPDATE SPARQL 1.1 Update Latest version 7.2 RDF-MT RDF Semantics Latest version SPARQL SPARQL 1.1 Query Language Latest version 8 Appendix Acknowledgements The editor would like to thank the following individuals for their input into the creation of this document: Sandro Hawke, Birte Glimm, Andy Seaborne, Steve Harris, Arnaud Le Hors, Ivan Mikhailov, David Booth, Simon Johnston, Kjetil Kjernsmo, Gregg Reynolds, Leigh Dodds, Tim Berners-Lee, and Ian Davis Change Log Changes since Proposed Recommendation None Changes since Candidate Recommendation None Changes since Last Call Removed reference to REST