Table of Contents
The following is a description of the HTTP-based communication protocol for Sesame 2. Design consideration for the protocol included the rules for the REST architectural style. In brief, this means that URLs are used to represent resources and that standard HTTP methods (GET, PUT, etc.) are used to access these resources. Client properties such as the data formats that it can process are communicated to the server using HTTP headers like Accept and are not part of the URLs. This way, a resource identified by a specific URL can, for example, be presented as an HTML page to a web browser and as a binary content stream to a client library. For more in depth information about REST see http://en.wikipedia.org/wiki/REST, http://rest.blueoxen.net/ and http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm. More information about HTTP in general and HTTP headers in particular can be found in RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1.
The Sesame 2 HTTP communication protocol is a fully compliant superset of the SPARQL Protocol for RDF W3C Recommendation. The current version of the protocol additionally supports communication for SPARQL 1.1 Update operations, as described in the SPARQL 1.1 Protocol for RDF W3C Working Draft, as well as the SPARQL 1.1 Graph Store HTTP Protocol W3C Working Draft.
The REST architectural style implies that URLs are used to represent the various resources that are available on a server. This section gives a summary of the resources that are available from a Sesame server with the HTTP-methods that can be used on them. In this overview, <SESAME_URL> is used to denote the location of the Sesame server, e.g. http://localhost/openrdf-sesame. Likewise, <REP_ID> denotes the ID of a specific repository (e.g. "mem-rdf"), and <PREFIX> denotes a namespace prefix (e.g. "rdfs").
The following is an overview of the resources that are available from a Sesame server.
<SESAME_URL> /protocol : protocol version (GET) /repositories : overview of available repositories (GET) /<REP_ID> : query evaluation and administration tasks on a repository (GET/POST/DELETE) /statements : repository statements (GET/POST/PUT/DELETE) /contexts : context overview (GET) /size : #statements in repository (GET) /rdf-graphs : named graphs overview (GET) /service : Graph Store operations on indirectly referenced named graphs in repository (GET/PUT/POST/DELETE) /<NAME> : Graph Store operations on directly referenced named graphs in repository (GET/PUT/POST/DELETE) /namespaces : overview of namespace definitions (GET/DELETE) /<PREFIX> : namespace-prefix definition (GET/PUT/DELETE)
The version of the protocol that the server uses to communicate over HTTP is available at: <SESAME_URL>/protocol. The version described by this chapter is "6".
Supported methods on this URL are:
An overview of the repositories that are available on a server can be retrieved from <SESAME_URL>/repositories.
Supported methods on this URL are:
Request headers:
Request:
GET /openrdf-sesame/repositories HTTP/1.1 Host: localhost Accept: application/sparql-results+xml, */*;q=0.5
Response:
HTTP/1.1 200 OK Content-Type: application/sparql-results+xml;charset=UTF-8 <?xml version='1.0' encoding='UTF-8'?> <sparql xmlns='http://www.w3.org/2005/sparql-results#'> <head> <variable name='uri'/> <variable name='id'/> <variable name='title'/> <variable name='readable'/> <variable name='writable'/> </head> <results ordered='false' distinct='false'> <result> <binding name='uri'> <uri>http://localhost/openrdf-sesame/repositories/mem-rdf</uri> </binding> <binding name='id'> <literal>mem-rdf</literal> </binding> <binding name='title'> <literal>Main Memory RDF repository</literal> </binding> <binding name='readable'> <literal datatype='http://www.w3.org/2001/XMLSchema#boolean'>true</literal> </binding> <binding name='writable'> <literal datatype='http://www.w3.org/2001/XMLSchema#boolean'>false</literal> </binding> </result> </results> </sparql>
Queries on a specific repository with ID <ID> can be evaluated by sending requests to: <SESAME_URL>/repositories/<ID>. This resource represents a SPARQL query endpoint. Both GET and POST methods are supported. The GET method is preferred as it adheres to the REST architectural style. The POST method should be used in cases where the length of the (URL-encoded) query exceeds practicable limits of proxies, servers, etc. In case a POST request is used, the query parameters should be send to the server as www-form-urlencoded data.
Parameters:
Request headers:
Request:
GET /openrdf-sesame/repositories/mem-rdf?query=select%20%3Cfoo:bar%3E&queryLn=serql HTTP/1.1 Host: localhost Accept: application/sparql-results+xml, */*;q=0.5
Response:
HTTP/1.1 200 OK Content-Type: application/sparql-results+xml;charset=UTF-8 <?xml version='1.0' encoding='UTF-8'?> <sparql xmlns='http://www.w3.org/2005/sparql-results#'> <head> <variable name='<foo:bar>'/> </head> <results ordered='false' distinct='false'> <result> <binding name='<foo:bar>'> <uri>foo:bar</uri> </binding> </result> </results> </sparql>
Request:
POST /openrdf-sesame/repositories/mem-rdf HTTP/1.1 Host: localhost Content-Type: application/x-www-form-urlencoded Accept: application/rdf+xml, */*;q=0.5 query=construct%20{?s%20?p%20?o}%20where%20{?s%20?p%20?o}
Response:
HTTP/1.1 200 OK Content-Type: application/rdf+xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> </rdf:RDF>
A specific repository with ID <ID> can be deleted from the server by sending requests to: <SESAME_URL>/repositories/<ID>. The DELETE method should be used for this, and the request accepts no parameters.
Care should be taken with the use of this method: the result of this operation is the complete removal of the repository from the server, including its configuration settings and (if present) data directory.
The statements for a specific repository with ID <ID> are available at: <SESAME_URL>/repositories/<ID>/statements
Supported methods on this URL are:
Parameters:
Request headers:
Request:
GET /openrdf-sesame/repositories/mem-rdf/statements HTTP/1.1 Host: localhost Accept: application/rdf+xml
Response:
HTTP/1.1 200 OK Content-Type: application/rdf+xml;charset=UTF-8 [RDF/XML ENCODED RDF DATA]
Request:
GET /openrdf-sesame/repositories/mem-rdf/statements?context=_:n1234x5678 HTTP/1.1 Host: localhost Accept: application/rdf+xml
Response:
HTTP/1.1 200 OK Content-Type: application/rdf+xml;charset=UTF-8 [RDF/XML ENCODED RDF DATA]
Request:
DELETE /openrdf-sesame/repositories/mem-rdf/statements HTTP/1.1 Host: localhost
Response:
HTTP/1.1 204 NO CONTENT
Request:
POST /openrdf-sesame/repositories/mem-rdf/statements HTTP/1.1 Host: localhost Content-Type: application/rdf+xml;charset=UTF-8 [RDF/XML ENCODED RDF DATA]
Response:
HTTP/1.1 204 NO CONTENT
Request:
PUT /openrdf-sesame/repositories/mem-rdf/statements HTTP/1.1 Host: localhost Content-Type: application/rdf+xml;charset=UTF-8 [RDF/XML ENCODED RDF DATA]
Response:
HTTP/1.1 204 NO CONTENT
Request:
PUT /openrdf-sesame/repositories/mem-rdf/statements?context=%3Curn:x-local:graph1%3E&baseURI=%3Curn:x-local:graph1%3E HTTP/1.1 Host: localhost Content-Type: application/x-turtle;charset=UTF-8 [TURTLE ENCODED RDF DATA]
Response:
HTTP/1.1 204 NO CONTENT
Request:
POST /openrdf-sesame/repositories/mem-rdf/statements?context=null HTTP/1.1 Host: localhost Content-Type: application/x-turtle;charset=UTF-8 [TURTLE ENCODED RDF DATA]
Response:
HTTP/1.1 204 NO CONTENT
Request:
POST /openrdf-sesame/repositories/mem-rdf/statements HTTP/1.1 Host: localhost Content-Type: application/x-www-form-urlencoded update=INSERT%20{?s%20?p%20?o}%20WHERE%20{?s%20?p%20?o}
Response:
HTTP/1.1 204 NO CONTENT
A list of resources that are used as context identifiers in a repository with ID <ID> is available at: <SESAME_URL>/repositories/<ID>/contexts
Supported methods on this URL are:
Request headers:
Request:
GET /openrdf-sesame/repositories/mem-rdf/contexts HTTP/1.1 Host: localhost Accept: application/sparql-results+xml
Response:
HTTP/1.1 200 OK Content-Type: application/sparql-results+xml <?xml version='1.0' encoding='UTF-8'?> <sparql xmlns='http://www.w3.org/2005/sparql-results#'> <head> <variable name='contextID'/> </head> <results ordered='false' distinct='false'> <result> <binding name='contextID'> <uri>urn:x-local:graph1</uri> </binding> </result> </results> </sparql>
Namespace declaration lists for a repository with ID <ID> are available at: <SESAME_URL>/repositories/<ID>/namespaces.
Supported methods on this URL are:
Request headers:
Request
GET /openrdf-sesame/repositories/mem-rdf/namespaces HTTP/1.1 Host: localhost Accept: application/sparql-results+xml, */*;q=0.5
Response:
HTTP/1.1 200 OK Content-Type: application/sparql-results+xml <?xml version='1.0' encoding='UTF-8'?> <sparql xmlns='http://www.w3.org/2005/sparql-results#'> <head> <variable name='prefix'/> <variable name='namespace'/> </head> <results ordered='false' distinct='false'> <result> <binding name='prefix'> <literal>rdf</literal> </binding> <binding name='namespace'> <literal>http://www.w3.org/1999/02/22-rdf-syntax-ns#</literal> </binding> </result> </results> </sparql>
Namespace declarations with prefix <PREFIX> for a repository with ID <ID> are available at: <SESAME_URL>/repositories/<ID>/namespaces/<PREFIX>.
Supported methods on this URL are:
Request
GET /openrdf-sesame/repositories/mem-rdf/namespaces/rdf HTTP/1.1 Host: localhost
Response:
HTTP/1.1 200 OK Content-Type: text/plain;charset=UTF-8 http://www.w3.org/1999/02/22-rdf-syntax-ns#
Request:
PUT /openrdf-sesame/repositories/mem-rdf/namespaces/example HTTP/1.1 Host: localhost Content-Type: text/plain http://www.example.com
Response:
HTTP/1.1 204 NO CONTENT
The repository size (defined as the number of statements it contains) is available at: <SESAME_URL>/repositories/<ID>/size.
Supported methods on this URL are:
Parameters:
Request
GET /openrdf-sesame/repositories/mem-rdf/size HTTP/1.1 Host: localhost
Response:
HTTP/1.1 200 OK Content-Type: text/plain 123456
The SPARQL 1.1 Graph Store HTTP Protocol is supported on a per-repository basis. The functionality is accessible at <SESAME_URL>/repositories/<ID>/rdf-graphs/service (for indirectly referenced named graphs), and <SESAME_URL>/repositories/<ID>/rdf-graphs/<NAME> (for directly referenced named graphs). A request on a directly referenced named graph entails that the request URL itself is used as the named graph identifier in the repository.
Supported methods on these resources are:
Request headers:
For requests on indirectly referenced graphs, the following parameters are supported:
Each reqest on an indirectly referenced graph needs to specify precisely one of the above parameters.
Request:
GET /openrdf-sesame/repositories/mem-rdf/rdf-graphs/graph1 HTTP/1.1 Host: localhost Accept: application/rdf+xml
Response:
HTTP/1.1 200 OK Content-Type: application/rdf+xml;charset=UTF-8 [RDF/XML ENCODED RDF DATA]
Request:
GET /openrdf-sesame/repositories/mem-rdf/rdf-graphs/service?graph=http%3A%2F%2Fexample.org%2Fgraph1 HTTP/1.1 Host: localhost Accept: application/rdf+xml
Response:
HTTP/1.1 200 OK Content-Type: application/rdf+xml;charset=UTF-8 [RDF/XML ENCODED RDF DATA]
Request:
GET /openrdf-sesame/repositories/mem-rdf/rdf-graphs/service?default HTTP/1.1 Host: localhost Accept: application/rdf+xml
Response:
HTTP/1.1 200 OK Content-Type: application/rdf+xml;charset=UTF-8 [RDF/XML ENCODED RDF DATA]
Request:
POST /openrdf-sesame/repositories/mem-rdf/rdf-graphs/graph1 HTTP/1.1 Host: localhost Content-Type: application/x-turtle;charset=UTF-8 [TURTLE ENCODED RDF DATA]
Response:
HTTP/1.1 204 NO CONTENT
The following table summarizes the MIME types for various document formats that are relevant to this protocol.
Table 8.1. MIME types for RDF formats
Format | MIME type |
---|---|
RDF/XML | application/rdf+xml |
N-Triples | text/plain |
Turtle | application/x-turtle |
N3 | text/rdf+n3 |
TriX | application/trix |
TriG | application/x-trig |
Sesame Binary RDF | application/x-binary-rdf |
Note: Sesame currently does not support N3 as an input format. For N3 documents that only use the basic N3 features, the Turtle format can be used instead.
Table 8.2. MIME types for variable binding formats
Format | MIME type |
---|---|
SPARQL Query Results XML Format | application/sparql-results+xml |
>SPARQL Query Results JSON Format | application/sparql-results+json |
binary RDF results table format | application/x-binary-rdf-results-table |
Table 8.3. MIME types for boolean result formats
Format | MIME type |
---|---|
SPARQL Query Results XML Format | application/sparql-results+xml |
plain text boolean result format | text/boolean |