In order to get access to non-public repositories on a Sesame server, one needs to log in to it. To do this, a request should be sent to http://HOSTNAME/SESAME_DIR/servlets/login, supplying the following parameters:

If the log in attempt succeeded, Sesame will respond with HTTP-code 200 ("OK") and will supply a cookie with a session ID that should be supplied for authentication in subsequent requests. The name of this cookie is sesame_sid.

If an invalid request is sent (e.g. the username is missing or the password was incorrect) Sesame will respond with an HTTP error code and a free format error message.

To log out from a Sesame server, one needs to send a request to http://HOSTNAME/SESAME_DIR/servlets/logout, supplying a session ID cookie that has been received earlier while logging in. Duplicate log out requests or log out requests for non-existing sessions are silently ignored.

Sesame will respond with HTTP-code 200 ("OK") and a free format text telling you that you have been logged out.

Information on available repositories can be acquired from Sesame by sending an HTTP-GET request to http://HOSTNAME/SESAME_DIR/servlets/listRepositories. This request requires no parameters, other than the optional session cookie.

Sesame will respond with HTTP-code 200 ("OK"). The body of the response contains an XML-document describing the repositories available to the user that is currently logged in (if any). This XML-document will adhere to the following DTD:

<!ELEMENT repositorylist (repository)*>
<!ELEMENT repository     (title)>
<!ELEMENT title          (#PCDATA)>

<!ATTLIST repository
          id        ID           #REQUIRED
          readable  (true|false) #REQUIRED
          writeable (true|false) #REQUIRED>

The following is an example output with two repositories, one read-write and one read-only.

<?xml version="1.0" encoding="UTF-8"?>
<repositorylist>
    <repository id="repository1" readable="true" writeable="true">
        <title>Public repository</title>
    </repository>
    <repository id="repository2" readable="true" writeable="false">
        <title>Repository 2</title>
    </repository>
</repositorylist>

The value of the id attribute is the identifier of the repository. This identifier can be used in consecutive requests to Sesame to specify which repository that request is about.

SeRQL-select, RQL and RDQL queries are all queries that return, in some way or another, sets of variable bindings or table-like results. SeRQL-construct queries are a different type of queries that return free-form RDF documents. Details about SeRQL-construct queries can be found in Evaluating a SeRQL-construct query.

SeRQL-select, RQL and RDQL queries can be sent to http://HOSTNAME/SESAME_DIR/servlets/evaluateTableQuery. The multipart/form-data encoded HTTP-POST method is the preferred method. HTTP-GET is also supported but can only be used if all parameter values consists of ASCII characters only. All requests can or must include the following parameters:

If all went well, Sesame responds with HTTP-code 200 ("OK") and the results of the query evaluation. The resultFormat and serialization parameters determine the format of the results and the Content-Type header of the response:

If the selected result format is xml, the output will look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<tableQueryResult>
  <header>
    <columnName>X</columnName>
    <columnName>Y</columnName>
  </header>
  <tuple>
    <uri>http://www.foo.com/schema.rdf#change</uri>
    <literal>Change</literal>
  </tuple>
  <tuple>
    <bNode>node001</bNode>
    <literal datatype="http://www.w3.org/2001/XMLSchema#int">256</literal>
  </tuple>
</tableQueryResult>

The document starts with a header listing the names of all result columns. The names of these columns often represent variable names, but this is not guaranteed. Some query languages also allow you to use constants or functions in a query's projection. In that case, the name of the column will be the constant and the function, respectively.

Following the header, zero or more tuple-elements will follow, one for each query result (or row in the table). Each result consists of a sequence of URIs, bNodes (blank nodes, also know as anonymous nodes), and/or literals. The values appear in the order in which they were specified in the query, which is the same as the order in the header.

The example output above shows how URIs, bNodes and literals (with their optional language encoding or datatype) are exported. Next to these three, there is a fourth type of value that is only exported by the RQL engine: intersections of classes. If a query asks for a domain or range of a property, then this domain or range can consist of the intersection of zero or more classes. These intersections are exported in intersection elements containing zero or more URIs and bNodes:

<?xml version="1.0" encoding="UTF-8"?>
<tableQueryResult>
  <tuple>
    <uri>http://www.icom.com/schema1.rdf#creates</uri>
    <intersection>
      <uri>http://www.icom.com/schema1.rdf#Artifact</uri>
      <uri>http://www.schemas.org/general#Stuff</uri>
    </intersection>
  </tuple>
</tableQueryResult>

When a property doesn't have any range restrictions, its range will be an empty intersection element. Domains or ranges that consist of exactly one class are exported as normal resources (see first example), and not as intersections.

If an error occurred while the request was being processed, Sesame will send back an HTTP error code (i.e. not 200) and a free format error message.

SeRQL-construct queries can be sent to http://HOSTNAME/SESAME_DIR/servlets/evaluateGraphQuery. The multipart/form-data encoded HTTP-POST method is the preferred method. HTTP-GET is also supported but can only be used if all parameter values consists of ASCII characters only. All requests can or must include the following parameters:

If all went well, Sesame responds with HTTP-code 200 (i.e. "OK") and the results of the query evaluation. The serialization parameter determines the encoding of the returned RDF document and the Content-Type header of the response:

What follows are three examples of one and the same RDF document (a possible query result) in different encodings.

XML-encoded RDF:

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xml:lang="en" 
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:cult="http://www.icom.com/schema.rdf#">

  <cult:Cubist rdf:about="http://www.european-history.com/picasso.html">
    <cult:paints>
      <cult:Painting rdf:about="http://www.european-history.com/jpg/guernica03.jpg">
        <cult:technique>oil on canvas</cult:technique>
      </cult:Painting>
    </cult:paints>
    <cult:first_name>Pablo</cult:first_name>
    <cult:last_name>Picasso</cult:last_name>
  </cult:Cubist>
</rdf:RDF>

N-Triples:

<http://www.european-history.com/picasso.html> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.icom.com/schema.rdf#Cubist>.
<http://www.european-history.com/picasso.html> <http://www.icom.com/schema.rdf#paints> <http://www.european-history.com/jpg/guernica03.jpg>.
<http://www.european-history.com/jpg/guernica03.jpg> <http://www.w3.org/1999/02/22-rdf-syntax#type> <http://www.icom.com/schema.rdf#Painting>.
<http://www.european-history.com/jpg/guernica03.jpg> <http://www.icom.com/schema.rdf#technique> "oil on canvas"@en.
<http://www.european-history.com/picasso.html> <http://www.icom.com/schema.rdf#first_name> "Pablo"@en.
<http://www.european-history.com/picasso.html> <http://www.icom.com/schema.rdf#last_name> "Picasso"@en.

Turtle:

@prefix cult: <http://www.icom.com/schema.rdf#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<http://www.european-history.com/jpg/guernica03.jpg> a cult:Painting ;
    cult:technique "oil on canvas"@en .
<http://www.european-history.com/picasso.html> a cult:Cubist ;
    cult:paints <http://www.european-history.com/jpg/guernica03.jpg> ;
    cult:first_name "Pablo"@en ;
    cult:last_name "Picasso"@en .

If an error occurred while the request was being processed, Sesame will send back an HTTP error code (i.e. not 200) and a free format error message.

Ontologies and data can be extracted from Sesame by sending a request to http://HOSTNAME/SESAME_DIR/servlets/extractRDF. This operation supports both multipart/form-data encoded HTTP-POST requests as well as HTTP-GET requests. Note that the latter can not be used when one of the parameter values contains non-ASCII characters.

The request must or can have the following parameters:

So, to extract the ontological data only (both explicit and inferred) from a repository test-db on host www.openrdf.org you can send an HTTP-GET request to the url http://www.openrdf.org/sesame/servlets/extractRDF?repository=test-db&serialization=rdfxml&onto=on.

If all went well, Sesame responds with HTTP-code 200 ("OK"). The body of the response contains the requested data. The serialization parameter determines the encoding and the Content-Type header of the response identically to what is described in Table 8.5, “RDF encodings for SeRQL-construct queries”.

If an invalid request is sent (e.g. the repository does not exist) Sesame will respond with an HTTP error code and a free format error message.

Data can be uploaded to Sesame by sending it to http://HOSTNAME/SESAME_DIR/servlets/uploadData, supplying the following parameters:

The response is always an HTTP-code 200 ("OK"). Streaming feedback is given on the progress, and warnings and errors are given if the data contains errors. If the selected format was html, then this feedback will be formatted in human-readable HTML (when displayed in a browser). If the selected format was xml, then the feedback will adhere to the following DTD:

<!ELEMENT transaction   (status | notification | warning | error)*>
<!ELEMENT status        (msg, line?, column?)>
<!ELEMENT notification  (msg, line?, column?, statement?)>
<!ELEMENT warning       (msg, line?, column?, statement?)>
<!ELEMENT error         (msg, line?, column?, statement?)>

<!ELEMENT msg           (#PCDATA)>
<!ELEMENT line          (#PCDATA)>
<!ELEMENT column        (#PCDATA)>

<!ELEMENT statement     ( (uri|bNode), uri, (uri|bNode|literal) )>
<!ELEMENT uri           (#PCDATA)>
<!ELEMENT bNode         (#PCDATA)>
<!ELEMENT literal       (#PCDATA)>
<!ATTLIST literal
      xml:lang CDATA #IMPLIED
      datatype CDATA #IMPLIED>

The following is a simple example of what the feedback might look like when incorrect data is uploaded to Sesame:

<?xml version="1.0" encoding="UTF-8"?>
<transaction>
    <status>
        <msg>Loading data</msg>
    </status>
    <status>
        <msg>Data loaded (756 bytes)</msg>
    </status>
    <status>
        <msg>Checking data for errors</msg>
    </status>
    <error>
      <msg>Not a legal integer: Hello World!</msg>
        <line>483</line>
        <column>42</column>
        <statement>
            <bNode>node1234</bNode>
            <uri>http://example.org/schema.rdf#age</uri>
            <literal datatype="http://www.w3.org/2001/XMLSchema#int">Hello World!</literal>
        </statement>
    </error>
</transaction>

Errors in the requests are signaled using HTTP error codes. Errors in the data are expressed in the streaming feedback.

Data can also be added to a repository by specifying a URL that points to the RDF data that should be added. To do this, send an HTTP-POST request to http://HOSTNAME/SESAME_DIR/servlets/uploadURL, supplying the following parameters:

The response format is identical to what is described in Data upload response format.

Errors in the requests are signaled using HTTP error codes. Errors in the data are expressed in the streaming feedback.

Data can be removed from Sesame by sending a request to http://HOSTNAME/SESAME_DIR/servlets/clearRepository. The following parameters are relevant to clearing a repository:

Identical to the reponse when adding data to a repository. See See Data upload response format. for more information.

Errors in the requests are signaled using HTTP error codes. Errors that occured while clearing the repository are expressed in the streaming feedback.

Data can be removed from Sesame by sending a requests to http://HOSTNAME/SESAME_DIR/servlets/removeStatements. Currently, Sesame only support removing of statements using statement patterns: one can specify a subject, predicate and/or object and all statements that match that pattern will be removed. The following parameters are relevant to the removal of statements:

Identical to the reponse when adding data to a repository. See Data upload response format for more information.

Errors in the requests are signaled using HTTP error codes. Errors that occured while removing statements from the repository are expressed in the streaming feedback.