Changes

BaseX offers a RESTful API for accessing database resources via URLs.REST ([httphttps://en.wikipedia.org/wiki/Representational_State_Transfer REpresentational State Transfer])facilitates a simple and fast access to databases through HTTP. The HTTP methodsGET, PUT, DELETE, and POST can be used to interact with the database.

By default, REST services are available at {{Code|http://localhost:89848080/rest/}}. If no default credentials are specified in the URL or when starting the web application, they will be requested by the client ([[Web Application#User Management|see further]]).

The root URL lists all available databases. The following examples assume thatyou have created a database instance from the [:<code>http://files.basex.orglocalhost:8080/xmlrest</factbook.xml factbook.xml] document:code>

:<code>http://localhost:8984/rest</code> <pre classlang="brush:xml"> <rest:databases resources="1" xmlns:rest="http://basex.org/rest"> <rest:database resources="125742" size="181359943813599">factbookarticles</rest:database> ...</rest:databases></pre>  The resources of a database (directories, resource metadata) are listed if a database and an optional directory path is specified:

The resources of a database can be listed by specifying the database, and potential sub directories, in the URL.In the given example, a single XML document is stored in the ''factbook'' database:<code>http://localhost:8080/rest/articles</code>

:<codepre lang="xml"><database name="articles" xmlns="http://localhost:8984basex.org/rest"> <dir>binaries</factbookdir> <resource type="xml" content-type="application/xml" size="77192">1973-02-08-xltp325.xml</resource> ...</database></codepre>

<pre class="brush:xml"> <rest:database name="factbook" resources="1" xmlns:rest="http://basex.org/rest"> <rest:If the path to a single resource type="xml" content-type="application/xml" size="77192">factbook.xml</rest:is specified, the resource></rest:database></pre> The contents of a database can itself will be retrieved by directly addressing the resourcereturned:

:<code>http://localhost:89848080/rest/factbookarticles/factbook1973-02-08-xltp325.xml</code> If a resource is not found, an HTTP response will be generated with <code>404</code> as status code.

If the GET method is used, all query parameters are directly specified within the URL.Additionally, the following '''operations''' can be specified:

* {{Code|query}}: Evaluate an XQuery expression. If a database or database path is specified in the URL, it is used set as initial query context.

* {{Code|run}}: Evaluate an XQuery file or command script located on the server. The file path is resolved against the {{Option|RESTPATH}} directory specified by <code>[[Options#WEBPATH. Similar to {{Code|query}}, a database or database path is set as context. With {{Announce|RESTPATH]]</code> (beforeVersion 11}}, if no file is found and if the file suffix has been omitted, it was resolved against <code>[[Options#WEBPATHthe extensions {{Code|.xq}} and {{Code|WEBPATH]]</code>).bxs}} are successively attached to the supplied filename.

* Lists all resources found in the '''tmp''' path of the ''factbook'' database:<br/><code>http://localhost:89848080/rest/factbook/tmp</code>* Returns the number of documents in a database called ''test'':<br/><code>http://localhost:8080/rest/test?query=count(.)</code>* Serializes a document as JsonML:<br/><code>http://localhost:8080/rest/factbook/factbook.xml?method=json&json=format=jsonml</code>* <code>US-ASCII</code> is chosen as output encoding, and the query <code>eval.xq</code> is evaluated:<br/><code>http://localhost:8080/rest?run=eval&encoding=US-ASCII</code>* The next URL lists all database users who are known to BaseX:<br/><code>http://localhost:8080/rest?command=show+users</code>

* Serializes a document as JSONML:<br/><code>http://localhost:8984/rest/factbook/factbook.xml?method=json&json=formatPOST Method==jsonml</code>

* <code>US-ASCII</code> The body of a POST request is chosen interpreted as output encodingXML fragment, and which specifies the query <code>evaloperation to perform.xq</code> is The name of the root element determines how the body will be evaluated:<br/><code>http://localhost:8984/rest?run=eval.xq&encoding=US-ASCII</code>

* The next URL lists all database users that are known to BaseX{{Code|commands}}:<br/><code>httpRun [[Commands#Command Scripts|Command Script]]* {{Code|query}}://localhostExecute XQuery expression* {{Code|run}}:8984/rest?Run server-side file (query or command script)* {{Code|command}}: Execute single command=show+users</code>

==POST Method==The root element may be bound to the optional REST namespace. Existing command scripts can be sent to the server without any modifications. For the other commands, the following child elements are supported:

The body of a POST request is interpreted as XML fragment{| class="wikitable"|-! Name! Description|-| {{Code|text}}| Required; contains the query string, which specifies thecommand string, or file to be run|-| {{Code|parameter}}| Serialization parameter (with {{Code|@name}} and {{Code|@value}} attributes)|-| {{Code|option}}| Database option (with {{Code|@name}} and {{Code|@value}} attributes)|-| {{Code|variable}}| Variable bindings|-| {{Code|context}}| Initial context itemoperation to perform. The body must conform to a given [[REST: POST Schema|XML Schema]].}

* The following query returns Create an empty database and return database information:  <pre lang="xml"><commands> <create-db name='db'/> <info-db/></commands></pre> Return the first five city names of the <b>factbook</b> database:  <pre classlang="brush:xml"><query rest xmlns="http://basex.org/rest"> <textrest><![CDATA[ (//city/name)[position() <= 5] ]]></text></queryrest>

* The second query returns the Return string lengths of all text nodes, which that are found in the node that has been specified as initial context node: <pre classlang="brush:xml"><rest:query xmlns:rest="http://basex.org/rest"> <rest:text>for $i in .//text() return string-length($i)</rest:text> <rest:context>

</rest:context></rest:query>

* The following request returns Return the registered database users encoded in <code>ISO-8859-1</code>: <pre classlang="brush:xml"><command xmlns="http://basex.org/rest">

* This example creates Create a new database from the specified input and retains preserve all whitespaces: <pre classlang="brush:xml"><command xmlns="http://basex.org/rest">

* The last request runs a Bind value to the {{Code|$person}} variable and run query <code>queryfind-person.xq</code> located in the directory specified by <code>[[Options#WEBPATH|WEBPATH]]</code>: <pre classlang="brush:xml"><run xmlns> <variable name="http://basex.org'person' value='Johannes Müller'/rest"> <text>queryfind-person.xq</text>

* '''Store as rawRaw Data''':<br/> If <code>application/octet-stream</code> is chosen as content-type, the input data is added as raw[[Binary Data]].

* A new database with the name <b>XMark</b> is created. If XML input is sent in the HTTP body, the resulting database resource will be called <b>XMark.xml</b>:<br/><code><nowiki>http://localhost:89848080/rest/XMark</nowiki></code>* A new database is created, and no whitespaces will be removed from the passed on XML input:<br/><code><nowiki>http://localhost:89848080/rest/XMark?chop=false</nowiki></code>* The contents of the HTTP body will be taken as input for the document <b>one.xml</b>, which will be stored in the <b>XMark</b> database:<br/><code><nowiki>http://localhost:89848080/rest/XMark/one.xml</nowiki></code>

An HTTP response with status code <code>201</code> (CREATED)is sent back if the operation was successful. Otherwise,the server will reply with <code>404</code> (if a specifieddatabase was not found) or <code>400</code> (if the operationcould not be completed).

Have Take a look at the [[REST#Usage Examples|usage examples]] for more detailed examples using Java and shell tools like cURL.

; ExampleExamples* The <b>factbook</b> database is deleted:<br/><code><nowiki>http://localhost:89848080/rest/factbook</nowiki></code>* All resources of the <b>XMark</b> database are deleted that reside in the <b>tmp</b> path:<br/><code><nowiki>http://localhost:89848080/rest/XMark/tmp/</nowiki></code>

All query Query parameters that have not been processed before otherwise will be treated as variable assignments:

* The following request assigns two variables to a server-side query file <code>mult.xq</code> placed in the HTTP directory:<br/><code>http://localhost:89848080/rest?run=mult.xqmultiply&$a=21&$b=2</code>assigns two variables and invokes <code>multiply.xq</code>:<pre classlang="brush:'xquery"'>(: XQuery file: multmultiply.xq :)

If <code>query</code> or <code>run</code> is used as an operation, external variables can be specified via the <code><variable/></code> element:

<pre classlang="brush:xml">

declare variable $x a as xs:integer external; declare variable $y b as xs:integer external;

#* <code>xml</code>, <code>adaptive</code>, <code>basex</code> → <code>application/xml</code>

:<code>http://localhost:89848080/rest?query=%3Ca/%3E</code><br/><code>http://localhost:89848080/rest?query=%3Ca/%3E&method=xml</code><br/><code>http://localhost:89848080/rest?query=%3Ca/%3E&media-type=application/xml</code>

<pre classlang="brush:java">

URL url = new URL("http://localhost:89848080/rest/factbook");

// Encode user name username and password pair with a base64 implementation.

<pre classlang="brush:java">

Tools such as the Linux commands [httphttps://www.gnu.org/s/wget/ Wget] or [http://curl.haxx.se/ cURL] exist to

* <code><nowiki>curl -i "http://localhost:89848080/rest/factbook?query=//city/name"</nowiki></code>

* <code><nowiki>curl -i -X POST -H "Content-Type: application/xml" -d "&lt;query xmlns='http://basex.org/rest'&gt;&lt;text&gt;//city/name&lt;/text&gt;&lt;/query&gt;" "http://localhost:89848080/rest/factbook"</nowiki></code>* <code><nowiki>curl -i -X POST -H "Content-Type: application/xml" -T query.xml "http://localhost:89848080/rest/factbook"</nowiki></code>

* <code><nowiki>curl -i -X PUT -T "etc/xml/factbook.xml" "http://localhost:89848080/rest/factbook"</nowiki></code>* <code><nowiki>curl -i -X PUT -H "Content-Type: application/json" -T "plain.json" "http://localhost:89848080/rest/plain"</nowiki></code>

* <code><nowiki>curl -i -X DELETE "http://admin:admin@localhost:89848080/rest/factbook"</nowiki></code>

* Added: support Support for input-specific content-type parameters* Updated: the The [[#GET Method|run operation]] now resolves file paths against the [[Options#RESTPATH{{Option|RESTPATH]] }} option.

* Removed: direct Direct evaluation of adresses resources with <code>application/xquery</code> as content type