Chapter 8. HTTP communication protocol for Sesame 2

Table of Contents

8.1. Protocol summary
8.2. Protocol version
8.2.1. Request examples
8.3. Repository list
8.3.1. Request examples
8.4. Repository queries
8.4.1. Requests examples
8.5. Repository removal
8.5.1. Request examples
8.6. Repository statements
8.6.1. Request examples
8.7. Context lists
8.7.1. Request examples
8.8. Namespace declaration lists
8.8.1. Request examples
8.9. Namespace declarations
8.9.1. Request examples
8.10. Repository size
8.10.1. Request examples
8.11. Graph Store support
8.11.1. Request examples
8.12. Content types
8.13. TODO

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.

8.1. Protocol summary

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)

8.2. Protocol version

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:

  • GET: Gets the protocol version string, e.g. "1", "2", etc.

8.2.1. Request examples

8.2.1.1. Fetch the protocol version

Request:

                    GET /openrdf-sesame/protocol HTTP/1.1
                    Host: localhost

Response:

                    HTTP/1.1 200 OK
                    Content-Type: text/plain;charset=UTF-8
                    Content-Length: 1

                    4

8.3. Repository list

An overview of the repositories that are available on a server can be retrieved from <SESAME_URL>/repositories.

Supported methods on this URL are:

  • GET: Gets an list of available repositories, including ID, title, read- and write access parameters for each listed repository. The list is formatted as a tuple query result with variables "uri", "id", "title", "readable" and "writable". The "uri" value gives the URI/URL for the repository and the "readable" and "writable" values are xsd:boolean typed literals indicating read- and write permissions.

Request headers:

8.3.1. Request examples

8.3.1.1. Fetch the repository list

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>

8.4. Repository queries

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:

  • 'query': The query to evaluate.
  • 'queryLn' (optional): Specifies the query language that is used for the query. Acceptable values are strings denoting the query languages supported by the server, i.e. "serql" for SeRQL queries and "sparql" for SPARQL queries. If not specified, the server assumes the query is a SPARQL query.
  • 'infer' (optional): Specifies whether inferred statements should be included in the query evaluation. Inferred statements are included by default. Specifying any value other than "true" (ignoring case) restricts the query evluation to explicit statements only.
  • '$<varname>' (optional): specifies variable bindings. Variables appearing in the query can be bound to a specific value outside the actual query using this option. The value should be an N-Triples encoded RDF value.
  • '$<timeout>' (optional): specifies a maximum query execution time, in whole seconds. The value should be an integer. A setting of 0 or a negative number indicates unlimited query time (the default).

Request headers:

8.4.1. Requests examples

8.4.1.1. Evaluate a SeRQL-select query on repository "mem-ref"

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='&lt;foo:bar&gt;'/>
                    </head>
                    <results ordered='false' distinct='false'>
                        <result>
                        <binding name='&lt;foo:bar&gt;'>
                            <uri>foo:bar</uri>
                        </binding>
                        </result>
                    </results>
                </sparql>

8.4.1.2. Evaluate a SPARQL-construct query on repository "mem-ref" using a POST request

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>

8.4.1.3. Evaluate a SPARQL-ask query on repository "mem-ref"

Request:

                    GET /openrdf-sesame/repositories/mem-rdf?query=ask%20{?s%20?p%20?o} HTTP/1.1
                    Host: localhost
                    Accept: text/boolean, */*;q=0.5

Response:

                    HTTP/1.1 200 OK
                    Content-Type: text/boolean;charset=US-ASCII

                    true

8.5. Repository removal

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.

8.5.1. Request examples

8.5.1.1. Remove the "mem-rdf" repository

Request:

	DELETE /openrdf-sesame/repositories/mem-rdf HTTP/1.1
	Host: localhost

Response:

	HTTP/1.1 204 NO CONTENT

8.6. Repository statements

The statements for a specific repository with ID <ID> are available at: <SESAME_URL>/repositories/<ID>/statements

Supported methods on this URL are:

  • GET: Fetches statements from the repository.
  • PUT: Updates data in the repository, replacing any existing data with the supplied data. The data supplied with this request is expected to contain an RDF document in one of the supported RDF formats.
  • DELETE: Deletes statements from the repository.
  • POST: Performs updates on the data in the repository. The data supplied with this request is expected to contain either an RDF document, a SPARQL 1.1 Update string, or a special purpose transaction document. If an RDF document is supplied, the statements found in the RDF document will be added to the repository. If a SPARQL 1.1 Update string is supplied, the update operation will be parsed and executed. If a transaction document is supplied, the updates specified in the transaction document will be executed.

Parameters:

  • 'subj' (optional): Restricts a GET or DELETE operation to statements with the specified N-Triples encoded resource as subject.
  • 'pred' (optional): Restricts a GET or DELETE operation to statements with the specified N-Triples encoded URI as predicate.
  • 'obj' (optional): Restricts a GET or DELETE operation to statements with the specified N-Triples encoded value as object.
  • 'update' (optional): Only relevant for POST operations. Specifies the SPARQL 1.1 Update string to be executed. The value is expected to be a syntactically valid SPARQL 1.1 Update string.
  • 'context' (optional): If specified, restricts the operation to one or more specific contexts in the repository. The value of this parameter is either an N-Triples encoded URI or bnode ID, or the special value 'null' which represents all context-less statements. If multiple 'context' parameters are specified, the request will operate on the union of all specified contexts. The operation is executed on all statements that are in the repository if no context is specified.
  • 'infer' (optional): Specifies whether inferred statements should be included in the result of GET requests. Inferred statements are included by default. Specifying any value other than "true" (ignoring case) restricts the request to explicit statements only.
  • 'baseURI' (optional): Specifies the base URI to resolve any relative URIs found in uploaded data against. This parameter only applies to the PUT and POST method.

Request headers:

  • 'Accept': Relevant values for GET requests are the MIME types of supported RDF formats.
  • 'Content-Type': Must specify the encoding of any request data that is sent to a server. Relevant values are the MIME types of supported RDF formats, "application/x-rdftransaction" for a transaction document and "application/x-www-form-urlencoded" in case the parameters are encoded in the request body (as opposed to the being part of the request URL).

8.6.1. Request examples

8.6.1.1. Fetch all statements from repository "mem-rdf"

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]

8.6.1.2. Fetch all statements from a specific context in repository "mem-rdf"

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]

8.6.1.3. Remove all statements from the "mem-rdf" repository

Request:

                    DELETE /openrdf-sesame/repositories/mem-rdf/statements HTTP/1.1
                    Host: localhost

Response:

                    HTTP/1.1 204 NO CONTENT

8.6.1.4. Add data to the "mem-rdf" repository

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

8.6.1.5. Add data to the "mem-rdf" repository, replacing any and all existing data

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

8.6.1.6. Add data to a specific context in the "mem-rdf" repository, replacing any data that is currently in this context

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

8.6.1.7. Add statements without a context to the "mem-rdf" repository, ignoring any context information that is encoded in the supplied data

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

8.6.1.8. Perform update described in a SPARQL 1.1 Update string

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

8.6.1.9. Perform updates described in a transaction document and treat it as a single transaction

Request:

                    POST /openrdf-sesame/repositories/mem-rdf/statements HTTP/1.1
                    Host: localhost
                    Content-Type: application/x-rdftransaction

                    [TRANSACTION DATA]

Response:

                    HTTP/1.1 204 NO CONTENT

8.7. Context lists

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:

  • GET: Gets a list of resources that are used as context identifiers. The list is formatted as a tuple query result with a single variable "contextID", which is bound to URIs and bnodes that are used as context identifiers.

Request headers:

8.7.1. Request examples

8.7.1.1. Fetch all context identifiers from repository "mem-rdf"

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>

8.8. Namespace declaration lists

Namespace declaration lists for a repository with ID <ID> are available at: <SESAME_URL>/repositories/<ID>/namespaces.

Supported methods on this URL are:

  • GET: Gets a list of namespace declarations that have been defined for the repository. The list is formatted as a tuple query result with variables "prefix" and "namespace", which are both bound to literals.
  • DELETE: Removes all namespace declarations from the repository.

Request headers:

8.8.1. Request examples

8.8.1.1. Fetch all namespace declaration info

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>

8.8.1.2. Remove all namespace declarations from the repository.

Request:

                    DELETE /openrdf-sesame/repositories/mem-rdf/namespaces HTTP/1.1
                    Host: localhost

Response:

                    HTTP/1.1 204 NO CONTENT

8.9. Namespace declarations

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:

  • GET: Gets the namespace that has been defined for a particular prefix.
  • PUT: Defines or updates a namespace declaration, mapping the prefix to the namespace that is supplied in plain text in the request body.
  • DELETE: Removes a namespace declaration.

8.9.1. Request examples

8.9.1.1. Get the namespace for prefix 'rdf'

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#

8.9.1.2. Set the namespace for a specific prefix

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

8.9.1.3. Remove the namespace for a specific prefix

Request:

                    DELETE /openrdf-sesame/repositories/mem-rdf/namespaces/example HTTP/1.1
                    Host: localhost

Response:

                    HTTP/1.1 204 NO CONTENT

8.10. Repository size

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:

  • GET: Gets the number of statements in a repository.

Parameters:

  • 'context' (optional): If specified, restricts the operation to one or more specific contexts in the repository. The value of this parameter is either an N-Triples encoded URI or bnode ID, or the special value 'null' which represents all context-less statements. If multiple 'context' parameters are specified, the request will operate on the union of all specified contexts. The operation is executed on all statements that are in the repository if no context is specified.

8.10.1. Request examples

8.10.1.1. Get the size of repository 'mem-rdf'

Request

                    GET /openrdf-sesame/repositories/mem-rdf/size HTTP/1.1
                    Host: localhost

Response:

                    HTTP/1.1 200 OK
                    Content-Type: text/plain

                    123456

8.10.1.2. Get the size of a specific context in repository 'mem-rdf'

Request

                    GET /openrdf-sesame/repositories/mem-rdf/size?context=%3Curn:x-local:graph1%3E HTTP/1.1
                    Host: localhost

Response:

                    HTTP/1.1 200 OK
                    Content-Type: text/plain

                    4321

8.11. Graph Store support

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:

  • GET: fetches statements in the named graph from the repository.
  • PUT: Updates data in the named graph in the repository, replacing any existing data in the named graph with the supplied data. The data supplied with this request is expected to contain an RDF document in one of the supported RDF formats.
  • DELETE: Delete all data in the named graph in the repository.
  • POST: Updates data in the named graph in the repository, adding to any existing data in the named graph with the supplied data. The data supplied with this request is expected to contain an RDF document in one of the supported RDF formats.

Request headers:

For requests on indirectly referenced graphs, the following parameters are supported:

  • 'graph' (optional): specifies the URI of the named graph to be accessed.
  • 'default' (optional): specifies that the default graph is to be accessed. This parameter is expected to be present but have no value.

Each reqest on an indirectly referenced graph needs to specify precisely one of the above parameters.

8.11.1. Request examples

8.11.1.1. Fetch all statements from a directly referenced named graph in repository "mem-rdf"

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]

8.11.1.2. Fetch all statements from an indirectly referenced named graph in repository "mem-rdf"

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]

8.11.1.3. Fetch all statements from the default graph in repository "mem-rdf"

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]

8.11.1.4. Add statements to a directly referenced named graph in the "mem-rdf" repository

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

8.11.1.5. Clear a directly referenced named graph in the "mem-rdf" repository

Request:

                    DELETE /openrdf-sesame/repositories/mem-rdf/rdf-graphs/graph1 HTTP/1.1
                    Host: localhost
                    

Response:

                    HTTP/1.1 204 NO CONTENT

8.12. Content types

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

FormatMIME type
RDF/XMLapplication/rdf+xml
N-Triplestext/plain
Turtleapplication/x-turtle
N3text/rdf+n3
TriXapplication/trix
TriGapplication/x-trig
Sesame Binary RDFapplication/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

FormatMIME type
SPARQL Query Results XML Formatapplication/sparql-results+xml
>SPARQL Query Results JSON Formatapplication/sparql-results+json
binary RDF results table formatapplication/x-binary-rdf-results-table

Table 8.3. MIME types for boolean result formats

FormatMIME type
SPARQL Query Results XML Formatapplication/sparql-results+xml
plain text boolean result formattext/boolean

8.13. TODO

  • Document HTTP error codes
  • Decide on authentication/login mechanism
  • Describe use of HEAD and OPTIONS methods