REST Server Processes - eXist: A NoSQL Document Database and Application Platform (2015)

eXist: A NoSQL Document Database and Application Platform (2015)

Appendix B. REST Server Processes

eXist’s REST Server offers a great deal of functionality from a relatively simple API. This chapter tries to illustrate the various process (decision) flows evaluated by the REST Server when you make HTTP requests of it, so that you may better understand their actions. We do this through a series of diagrams linked to the different request types.

We also examine the optional and mandatory parameters that can be used with the REST Server to modify requests and responses.

GET Process Flow

Figure B-1. Process flow for HTTP GET requests in the REST Server

HEAD Process Flow

Figure B-2. Process flow for HTTP HEAD requests in the REST Server

PUT Process Flow

Figure B-3. Process flow for HTTP PUT requests in the REST Server

DELETE Process Flow

Figure B-4. Process flow for HTTP DELETE requests in the REST Server

POST Process Flow

Figure B-5. Process flow for HTTP POST requests in the REST Server

The boxes in the flowchart with dotted outlines (“Has cache Parameter?” and “Cache Results”) indicate that these steps are only considered when an XQuery is POSTed to the REST Server API, and not when a stored query is invoked using a POST request to the REST Server API.

REST Server Parameters

Next we detail the parameters available for use when you are making requests to eXist’s REST Server.

Note that several of the parameters are similar for GET and POST requests. Parameters are always written lowercase; however, when they are used in the query of a URL for an HTTP GET request they are also prefixed with an _ (underscore) character.

HTTP GET Parameters

The parameters detailed here can be used in the query string of a URL when you are performing an HTTP GET.

NOTE

When placing values into query parameters you may need to URL-encode them, depending on the HTTP client that you are using. Many HTTP clients (such as web browsers) will auto-encode the parameters. If you are using Java’s java.net.URLConnection, however, you should be aware that it does not auto-encode the parameters, and you will need to encode each value with java.net.URLEncoder.

Many client and server applications have a limit on the amount of data that can be placed into the URL query string, so if you are making complex queries you should consider using POST instead of GET. For more information, see “HTTP POST Parameters”.

For clarity, the query parameter values in Table B-1 are shown before encoding.

Name

Description

Example

cache

Used in combination with a query parameter, this parameter can instruct the REST Server to cache the results of the XQuery in RAM. This is especially useful when subsequently performing requests with the session, start, and howmany parameters to enable you to efficiently execute a query once, and then retrieve the results in pages. Once you are finished with a cached query, you should make another request with the release parameter set to yes to remove its results from memory on the server.

Cached results are assigned a session ID, which you need to use in subsequent requests. The session ID is returned in the exist:result/@session attribute (see “wrap XML grammar”) if thewrap parameter is not set to no, and also in the HTTP response header X-Session-Id.

The value of the parameter should be either yes or no.

http://localhost:8080/exist/rest/db/my-collection/?_query=/a/b/c&_cache=yes

encoding

Can be used to specify the character encoding that should be used by the serializer for the result document.

The value of the parameter should be the name of a character encoding supported by your JRE (e.g., UTF-16). eXist uses UTF-8 by default.

http://localhost:8080/exist/rest/db/my-collection/?_query=//my-node&_encoding=UTF-16

howmany

Used in combination with a query parameter to indicate how many results should be returned from the query (if the query returns a sequence of items). This can also be used in combination withstart to easily create a paging mechanism.

The value of the parameter should be an integer value of 1 or more. Using a number greater than the number of available results will simply result in all results being returned.

http://localhost:8080/exist/rest/db/my-collection/?_query=/a/b/c&_howmany=10

indent

Instructs the serializer to apply indentation to the formatting of the result document.

The value of the parameter should be either yes or no.

http://localhost:8080/exist/rest/db/my-collection/?_query//my-node&_indent=yes

query

Can be used to provide an XQuery to execute. The initial context of the XQuery is the document or collection indicated by the URI.

The value of the parameter should be an XQuery.

http://localhost:8080/exist/rest/db/my-collection/?_query/a/b/c

release

When the cache parameter is set to yes, the results of XPath and XQuery executions by the REST Server are cached. This parameter can be used to release the cached results of a query.

The value of the parameter should be the cached session ID returned in the result of the initial query.

http://localhost:8080/exist/rest/db/?_query=//my-node&_cache=yes&_release=7

session

Can be used to identify the results of a previous query where the cache parameter was used.

The value of the parameter should be a cached session ID returned by eXist in the response to a previous request made using the cache parameter.

http://localhost:8080/exist/rest/db/my-collection/?_session=7&_start=11&_howmany=10

source

When addressing a stored XQuery document, this parameter can be set to yes to retrieve the source code of the XQuery rather than execute it.

By default, this functionality is disabled in the configuration file $EXIST_HOME/descriptor.xml, but it can be enabled on a resource-by-resource basis if desired.

The value of the parameter should be either yes or no.

http://localhost:8080/exist/rest/db/my-collection/my-query.xquery?_source=yes

start

Used in combination with a query parameter to indicate where to start returning results from within the result sequence (if the query returns a sequence of items). This is typically used in combination with howmany to create a paging mechanism.

The value of the parameter should be an integer value of 1 or more. The result subsequence is calculated from start => results <= howmany.

http://localhost:8080/exist/rest/db/my-collection/?_query=/a/b/c&_start=11

typed

Used in combination with a query parameter to instruct the query serializer to add typing information to the elements of the result document.

The value of the parameter should be either yes or no.

http://localhost:8080/exist/rest/db/my-collection/?_query=//my-node&_typed=yes

variables

Can be used to provide one or more external variable values to bind into the XQuery static context, either in combination with a query parameter or through directly addressing and executing a stored XQuery.

The value of the parameter should be an XML document containing the variables as set out in “variables XML grammar”. Due to the nature of the parameter being an XML document, it can be much simpler to send this as part of an HTTP POST request (see “HTTP POST Parameters”) rather than a GET request.

http://localhost:8080/exist/rest/db/my-collection/my-query.xquery?_variables=<variables xmlns="http://exist.sourceforge.net/NS/exist" xmlns:sx="http://exist-db.org/xquery/types/serialized"><variable><qname><localname>my-var</localname></qname><sx:sequence><sx:value type="xs:string">some value</sx:value></sx:sequence></variable></variables>

wrap

When sending queries to the REST Server by using the query parameter, by default the result of the XQuery will be wrapped in an XML document, as described in “wrap XML grammar”. This parameter allows you to disable that wrapping. When directly addressing and executing stored XQueries, this parameter has no effect.

The value of the parameter should be either yes or no.

http://localhost:8080/exist/rest/db/my-collection/?_query=//my-node&_wrap=no

xpath

Can be used in the query string of a URL to provide an XPath to execute. The context of the XPath is the document or collection indicated by the URI. The value of the parameter should be an XPath expression.

This is deprecated in favor of the query parameter, which can accept either an XPath or an XQuery.

http://localhost:8080/exist/rest/db/my-collection/?_xpath=//my-node

xsl

Can be used to enable/disable the processing of XSL processing instructions in the result document by the serializer, or to apply a specific XSLT transformation to the result document.

The value of the parameter should be either yes, no, or a path to an XSLT document in the database. When using to enable processing of XSL processing instructions, note that this needs to also be enabled in the configuration file $EXIST_HOME/conf.xml.

http://localhost:8080/exist/rest/db/my-collection/?_query=//my-node&_xsl=/db/my-stylesheet.xslt

Table B-1. HTTP GET URL query parameters

HTTP POST Parameters

When making an HTTP POST request to eXist’s REST Server, you can send an XML document in the body describing an XQuery to be executed and parameters to control the execution and serialization of results. In many ways this is very similar to the process described in the previous section, but it uses POST and an XML document as opposed to GET and URL query parameters.

The XML grammar describing the XML document that can be sent in the body of an HTTP POST to the REST Server is as follows:

<exist:query xmlns:exist="http://exist.sourceforge.net/NS/exist

start? = number

max? = number

cache? = ("yes" | "no")

session? = string

typed? = ("yes" | "no")

(wrap = ("yes" | "no") | enclose = ("yes" | "no"))?

encoding? = string

method? = string>

(exist:text,

exist:variables?,

exist:properties?)

</exist:query>

The attributes on the exist:query element are documented in Table B-2, while the exist:text, exist:variables, and exist:properties elements are documented further in “text XML grammar”, “variables XML grammar”, and “properties XML grammar”, respectively.

Name

Description

Example

cache

Can be used to instruct the REST Server to cache the results of the XQuery in RAM. This is especially useful when subsequently performing requests with the session, start, and max parameters to enable you to efficiently execute a query once, and then retrieve the results in pages.

Cached results are assigned a session ID, which you need to use in subsequent requests. The session ID is returned in the exist:result/@session attribute (see “wrap XML grammar”) if the wrap parameter is not set to no, and also in the HTTP response header X-Session-Id.

The value of the parameter should be either yes or no.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

cache="yes">

<exist:text><![CDATA[

/a/b/c

]]></exist:text>

</exist:query>

enclose

When sending queries to the REST Server, by default the result of the XQuery will be wrapped in an XML document, as described in “wrap XML grammar”. This parameter allows you to disable that wrapping. When directly addressing and executing stored XQueries, this parameter has no effect.

The value of the parameter should be either yes or no.

This is deprecated in favor of the wrap parameter.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

enclose="no">

<exist:text><![CDATA[

//my-node

]]></exist:text>

</exist:query>

encoding

Can be used to specify the character encoding that should be used by the serializer for the result document.

The value of the parameter should be the name of a character encoding supported by your JRE (e.g., UTF-16). eXist uses UTF-8 by default.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

encoding="UTF-16">

<exist:text><![CDATA[

//my-node

]]></exist:text>

</exist:query>

max

Indicates how many results should be returned from the query (if the query returns a sequence of items). This can also be used in combination with start to easily create a paging mechanism.

The value of the parameter should be an integer value of 1 or more. Using a number greater than the number of available results will simply result in all results being returned.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

max="10">

<exist:text><![CDATA[

/a/b/c

]]></exist:text>

</exist:query>

method

Can be used in the body of a POST request when supplying an XQuery; it causes the results of the query to be serialized using the supplied serializer method.

Instructs the serializer to use a specific serialization method on the results of the query. For the JSON serialization format of XML used by eXist, see “JSON serialization”.

The value of the parameter must be either xml, xhtml, html, html5, json, or text.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

method="json">

<exist:text><![CDATA[

/a/b/c

]]></exist:text>

</exist:query>

session

Can be used to identify the results of a previous query where the cache parameter was used.

The value of the parameter should be a cached session ID returned by eXist in the response to a previous request made using the cache parameter.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

session="7"

start="11"

max="10">

<exist:text><![CDATA[

/a/b/c

]]></exist:text>

</exist:query>

start

Indicates where to start returning results from within the result sequence (if the query returns a sequence of items). This is typically used in combination with max to create a paging mechanism.

The value of the parameter should be an integer value of 1 or more. The result subsequence is calculated from start => results <= max.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

start="11">

<exist:text><![CDATA[

/a/b/c

]]></exist:text>

</exist:query>

typed

Instructs the query serializer to add typing information to the elements of the result document.

The value of the parameter should be either yes or no.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

typed="yes">

<exist:text><![CDATA[

//my-node

]]></exist:text>

</exist:query>

wrap

When sending queries to the REST Server, by default the result of the XQuery will be wrapped in an XML document, as described in “wrap XML grammar”. This parameter allows you to disable that wrapping. When directly addressing and executing stored XQueries, this parameter has no effect.

The value of the parameter should be either yes or no.

<exist:queryxmlns:exist="http://exist.sourceforge.net/NS/exist"

wrap="no">

<exist:text><![CDATA[

//my-node

]]></exist:text>

</exist:query>

Table B-2. HTTP POST request body parameters

Common XML Grammars for Parameters

This section details some of the common XML grammars used in GET and POST operations.

wrap XML grammar

The XML grammar describing the result document returned by the REST Server when the wrap request parameter is not set to no is formatted as follows:

<exist:result xmlns:exist="http://exist.sourceforge.net/NS/exist"

hits = number

start = number

count = number

session? = string>

any*

</exist:result>

properties XML grammar

The XML grammar for the properties request parameter has this format:

<exist:properties>

(exist:property+)

</exist:properties>

<exist:property

name = string

value = string/>

text XML grammar

The XML grammar for the text request parameter has this format:

<exist:text><![CDATA[

(: Your XQuery code here! :)

]]></exist:text>

variables XML grammar

The XML grammar for the variables request parameter has the following format, and you can see it in context in Example B-1:

<exist:variables xmlns:exist="http://exist.sourceforge.net/NS/exist">

(exist:variable+)

</exist:variables>

<exist:variable xmlns:sx="http://exist-db.org/xquery/types/serialized">

(exist:qname,

sx:sequence)

</exist:variable>

<exist:qname>

(exist:prefix?,

exist:localname,

exist:namespace?)

</exist:qname>

<sx:sequence>

(sx:value+)

</sx:sequence>

<sx:value type? = string>

(text() | element())

</sx:value>

Example B-1. variables XML document

<variables xmlns="http://exist.sourceforge.net/NS/exist"

xmlns:sx="http://exist-db.org/ xquery/types/serialized">

<variable>

<qname>

<localname>my-var</localname>

</qname>

<sx:sequence>

<sx:value type="xs:string">some value</sx:value>

</sx:sequence>

</variable>

<variable>

<qname>

<localname>author</localname>

<namespace>http://book/example/</namespace>

</qname>

<sx:sequence>

<sx:value>

<firstName xmlns="">Adam</firstName>

</sx:value>

<sx:value>

<lastName xmlns="">Retter</lastName>

</sx:value>

</sx:sequence>

</variable>

</variables>