REST-Style Web API
eXist-db provides a REST-style (or RESTful) API through HTTP, which provides a simple and quick way to access the database. To use this API, all one needs is an HTTP client, which is provided by nearly all programming languages and environments. Or simply use a web-browser…
In the standard eXIst-db configuration, the system will listen for REST request at:
The server treats all HTTP request paths as paths to a database collection (instead of the file system). Relative paths are resolved relative to the database root collection. For instance:
The server will receive an HTTP GET request for the resource
hamlet.xml in the collection
/db/shakespeare/plays. Itr will look for this collection and check if the resource is available. If so, it will retrieve
its contents and send this back to the client. If the document does not exist, an HTTP 404 (Not Found) status response will
To keep the interface simple, the basic database operations are directly mapped to HTTP request methods wherever possible:
Retrieves a resource or collection from the database. XQuery and XPath queries may also be specified using GET's optional parameters applied to the selected resource. See GET Requests.
Uploads a resource to the database. If required, collections are automatically created and existing resources overwritten. See PUT Requests.
Removes a resource (document or collection) from the database. See DELETE Requests.
Submits an XML fragment in the content of the request. This fragment specifies the action to take. The fragment can be either an XUpdate document or a query request. Query requests are used to pass complex XQuery expressions too large to be URL-encoded. See POST Requests.
When running eXist-db as a stand-alone server(when the database has been started using the shell-script
(Unix) or batch file
bin/server.bat (Windows/DOS)), HTTP access is supported through a simple, built-in web server. This
web server has limited capabilities, restricted to the basic operations defined by eXist's REST API (
When running in a servlet-context (the usual way of starting eXist-db), this same server functionality is provided by the
Both the stand-alone server and the servlet rely on Java class
org.exist.http.RESTServer to do the actual work.
Authentication is done through the basic HTTP authentication mechanism so only authenticated users can access the database. If no username
and password are specified, the server assumes a "guest" user identity, which has limited capabilities. If the username submitted is not known,
or an incorrect password is submitted, an error page (
403 - Forbidden) is returned.
If the server receives an HTTP
GET request, it first checks the request for known parameters. If no parameters are given or
known it will try to locate the collection or document specified in the URI database path and return a representation of this resource the
When the located resource is XML, the returned content-type attribute value is
for binary resources
If the path resolves to a database collection, the retrieved results are returned as an XML fragment. For example:
xml-stylesheet processing instruction is found in a requested XML document, the database will try to apply this
stylesheet before returning the document. A relative path will be resolved relative to the location of the source document. For example, if the
hamlet.xml, which is stored in collection
/db/shakespeare/plays contains the XSLT processing
<?xml-stylesheet type="application/xml" href="shakes.xsl"?>
The database will load the stylesheet from
GET accepts the following optional request parameters (which must be URL-encoded):
Applies an XSL stylesheet to the requested resource. A relative path is considered relative to the database root collection. This option will override any XSL stylesheet processing instructions found in the source XML file.
nodisables any stylesheet processing. This is useful for retrieving unprocessed XML from documents that have a stylesheet declaration.
If your document has a valid XSL stylesheet declaration, the web browser may still decide to apply the XSL. In this case, passing
_xsl=nohas no visible effect, though the XSL is now rendered by the browser, not eXist.
Executes the query specified. The collection or resource referenced in the request path is added to the set of statically known documents for the query.
_indent=yes | no
Whether to return indented pretty-printed XML. The default value is
_encoding=Character Encoding Type
Sets the character encoding for the resulting XML. The default value is
_howmany=Number of Items
Specifies the maximum number of items to return from the result sequence. The default value is
_start=Starting Position in Sequence
Specifies the index position of the first item in the result sequence to return. The default value is
_wrap=yes | no
Specifies whether the returned query results must be wrapped in a parent
<exist:result>element. The default value is
_source=yes | no
Specifies whether the query should display its source code instead of being executed. The default value is
no. See the
descriptor.xmlabout explicitly allowing this behaviour.
_cache=yes | no
If set to
yes, the results of the current query are stored in a session on the server. A session id will be returned with the response. Subsequent requests can pass this session id via the
_sessionparameter. If the server finds a valid session id, it will return the cached results instead of re-evaluating the query. See below.
Specifies a session id returned by a previous query request. Query results will be read from the cached session.
Release the session identified by session id.
As an example: The following URI will find all
<SPEECH> elements in the collection
/db/shakespeare with "Juliet"
<SPEAKER>. As specified, it will return 5 items from the result sequence, starting at position 3:
Documents can be stored or updated in the database using an HTTP
PUT request. The request URI points to the location where the
document must be stored. As defined by the HTTP specifications, an existing document at the specified path will be updated. Any collections
defined in the path that do not exist are created automatically.
For example, the following Python script stores a document (the name is specified on the command-line) in the database collection
/db/test,. This will be created if it does not exist. Note that the HTTP header field
application/xml, since otherwise the document would be stored as a binary resource.
DELETE removes a collection or resource from the database.
POST requests require an XML fragment in the content of the request. This fragment specifies the action to take.
If the root node of the fragment uses the XUpdate namespace (
http://www.xmldb.org/xupdate), the fragment is sent to the XUpdateProcessor to be processed.
Otherwise the root node must have the namespace for eXist requests (
http://exist.sourceforge.net/NS/exist). The fragment is interpreted as an extended query request. Extended query requests can be used to post complex XQuery scripts that are too large to be encoded in a
The structure of the POST XML request is as follows:
The root element
query identifies the fragment as an extended query request. The XQuery expression for this request is
enclosed in the
text element. The
attributes have the same meaning as the corresponding
GET parameters (see GET Requests).
You may have to enclose the XQuery expression in a CDATA section (i.e. <![CDATA[ ... ]]>) to avoid parsing errors.
Optional output properties, such as
pretty-print, can be passed in the
An example of
POST for Perl is provided below:
The returned query results are enclosed in an
The REST interface supports executing stored XQueries on the server. If the target resource of a
request is a binary resource with the mime-type
application/xquery, the REST server will try to compile and execute it as an
XQuery script. The script has access to the entire HTTP context, including parameters and session attributes.
When executing queries using
POST, the server is able to cache query results in a server-side session.
These results are cached in memory.
Memory consumption will be low for query results which reference nodes stored in the database and high for nodes constructed within the XQuery itself.
To create a session and store query results, pass
_cache=yes with a
GET request or set attribute
cache="yes" within the XML payload of a
POST query request. The server will execute the query as usual. If the
result sequence contains more than one item, the entire sequence will be stored into a newly created session.
The id of the created session is included in the response. For requests which return a
<exist:result> wrapper element, the session
id will be specified in the
exist:session attribute. The session id is also available in the HTTP header
The following example shows an example of the HTTP header and
<exist:result> tag returned by the server:
HTTP/1.1 200 OK Date: Thu, 01 May 2008 16:28:16 GMT Server: Jetty/5.1.12 (Linux/2.6.22-14-generic i386 java/1.6.0_03 Expires: Thu, 01 Jan 1970 00:00:00 GMT Last-Modified: Tue, 29 Apr 2008 20:34:33 GMT X-Session-Id: 2 Content-Type: application/xml; charset=UTF-8 Content-Length: 4699 <exist:result xmlns:exist="http://exist.sourceforge.net/NS/exist" exist:hits="3406" exist:start="1" exist:count="10" exist:session="2"> ... </exist:result>
The session id can be passed with subsequent requests to retrieve further chunks of data without re-evaluating the query. For a
GET request, pass the session id with parameter
_session. For a
POST request, add an attribute
session="sessionId" to the XML content of the request.
If the session does not exist or has timed out, the server will re-evaluate the query. The timeout is set to 2 minutes.
A session can be deleted by sending a GET
request to an arbitrary collection URL. Pass the session id in the