administrator, editor
31
edits
Changes
Jump to navigation
Jump to search
m
Create an empty database and return database information:
<syntaxhighlight lang="xml">
<commands>
<create-db name='db'/>
<info-db/>
</commands>
</syntaxhighlight>
Have Take a look at the [[REST#Usage Examples|usage examples]] for more detailed examples using Java and shell tools like cURL.
no edit summary
This page presents one of the [[Web Application]] services. It describes how to use the REST API of BaseX.
BaseX offers a RESTful API for accessing database resources via URLs.REST ([https://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.
=Usage=
Since BaseX 10, results in the {{Code|rest}} namespace are returned unprefixed:
<syntaxhighlight pre lang="xml">
<!-- before -->
<rest:databases xmlns:rest="http://basex.org/rest"/>
<!-- before BaseX 10 -->
<databases xmlns="http://basex.org/rest"/>
</syntaxhighlightpre>
=URL Architecture=
:<code>http://localhost:8080/rest</code>
<syntaxhighlight pre lang="xml">
<databases xmlns="http://basex.org/rest">
<database resources="25742" size="43813599">articles</database>
...
</databases>
</syntaxhighlightpre>
The resources of a database (directories, resource metadata) are listed if a database and an optional directory path is specified:
:<code>http://localhost:8080/rest/articles</code>
<syntaxhighlight pre lang="xml">
<database name="articles" xmlns="http://basex.org/rest">
<dir>binaries</dir>
...
</database>
</syntaxhighlightpre>
If the path to a single resource is specified, the resource itself will be returned:
==GET Method==
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 set as query context.
* {{Code|command}}: Execute a single [[Commands|database command]].
* {{Code|run}}: Evaluate an XQuery file or command script located on the server. The file path is resolved against the {{Option|RESTPATH}} directory. Similar to {{Code|query}}, a database or database path is set as context. With {{Announce|Version 11}}, if no file is found and if the file suffix has been omitted, the extensions {{Code|.xq}} and {{Code|.bxs}} are successively attached to the supplied filename.
; Examples
* Lists all resources found in the '''tmp''' path of the ''factbook'' database:<br/><code>http://localhost:8080/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 JSONMLJsonML:<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.xq&encoding=US-ASCII</code> * The next URL lists all database users that who are known to BaseX:<br/><code>http://localhost:8080/rest?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:
; Examples
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:
<syntaxhighlight pre lang="xml">
<rest xmlns="http://basex.org/rest">
<rest><![CDATA[ (//city/name)[position() <= 5] ]]></text>
</rest>
</syntaxhighlightpre>
Return string lengths of all text nodes that are found in the node that has been specified as initial context node:
<syntaxhighlight pre lang="xml">
<query>
<text>for $i in .//text() return string-length($i)</text>
</context>
</query>
</syntaxhighlightpre>
Return the registered database users encoded in <code>ISO-8859-1</code>:
<syntaxhighlight pre lang="xml">
<command>
<text>show users</text>
<parameter name='encoding' value='ISO-8859-1'/>
</command>
</syntaxhighlightpre>
Create a new database from the specified input and preserve all whitespaces:
<syntaxhighlight pre lang="xml">
<command>
<text>create db test http://files.basex.org/xml/xmark.xml</text>
<option name='chop' value='false'/>
</command>
</syntaxhighlightpre>
Bind value to the {{Code|$person}} variable and run query <code>find-person.xq</code>:
<syntaxhighlight pre lang="xml">
<run>
<variable name='person' value='Johannes Müller'/>
<text>find-person.xq</text>
</run>
</syntaxhighlightpre>
==PUT Method==
* 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:8080/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).
==DELETE Method==
The DELETE method is used to delete databases or resources within a database.
; ExampleExamples
* The <b>factbook</b> database is deleted:<br/><code><nowiki>http://localhost:8080/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:8080/rest/XMark/tmp/</nowiki></code>
; Example
The request <code>http://localhost:8080/rest?run=multiply.xq&a=21&b=2</code> assigns two variables and invokes <code>multiply.xq</code>:<syntaxhighlight pre lang="'xquery"'>
(: XQuery file: multiply.xq :)
declare variable $a as xs:integer external;
declare variable $b as xs:integer external;
<mult>{ $a * $b }</mult>
</syntaxhighlightpre>
; Example
{{Announce|Updated with Version 11:}} Support for multiple values.
The request <code>http://localhost:8080/rest?run=sum.xq&n=3&n=4&n=5</code> assigns multiple values to the same variable:<syntaxhighlight pre lang="'xquery"'>
(: XQuery file: sum.xq :)
declare variable $n as xs:integer* external;
sum($n)
</syntaxhighlightpre>
The dollar sign can be omitted as long as the variable name does not equal a parameter keyword (e.g.: <code>method</code>).
If <code>query</code> or <code>run</code> is used as an operation, external variables can be specified via the <code><variable/></code> element:
<syntaxhighlight pre lang="xml">
<query xmlns="http://basex.org/rest">
<text><![CDATA[
<variable name="b" value="2"/>
</query>
</syntaxhighlightpre>
=Response=
<code>org.basex.util.Base64</code> can be used for that purpose:
<syntaxhighlight pre lang="java">
import java.net.*;
import org.basex.util.*;
}
}
</syntaxhighlightpre>
===Content-Types===
the connection (in this example we explicitly store the input file as raw):
<syntaxhighlight pre lang="java">
// store input as raw
conn.setRequestProperty("Content-Type", "application/octet-stream");
</syntaxhighlightpre>
See the [[REST#PUT Requests|PUT Requests]] section for a description of the possible content-types.
;Version 11.0
* Updated: [[#Request|Request]]: The extensions {{Code|.xq}} and {{Code|.bxs}} are successively attached to the supplied filename.
* Updated: [[#Assigning Variables|Assigning Variables]]: Support for multiple values.
