Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
[[Category:Server]]
[[Category:HTTP]]
[[Category:Developer]]
→Command Line
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 methods
GET, PUT, DELETE, and POST can be used to interact with the database.
The root URL lists all available databases. The following examples assume that
you have created a database instance from the [httphttps://files.basex.org/xml/factbook.xml factbook.xml] document:
:<code>http://localhost:8984/rest</code>
<pre classsyntaxhighlight lang="brush:xml">
<rest:databases resources="1" xmlns:rest="http://basex.org/rest">
<rest:database resources="1" size="1813599">factbook</rest:database>
</rest:databases>
</presyntaxhighlight>
The resources of a database can be listed by specifying the database, and potential sub directories, in the URL.
:<code>http://localhost:8984/rest/factbook</code>
<pre classsyntaxhighlight lang="brush:xml">
<rest:database name="factbook" resources="1" xmlns:rest="http://basex.org/rest">
<rest:resource type="xml" content-type="application/xml" size="77192">factbook.xml</rest:resource>
</rest:database>
</presyntaxhighlight>
The contents of a database can be retrieved by directly addressing the resource:
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|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 directory specified by <code>[[Options#WEBPATH{{Option|RESTPATH]]</code> }} (before, it was resolved against <code>[[Options#WEBPATH{{Option|WEBPATH]]</code>}}). Similar to {{Code|query}}, a database or database path is set as context.
; Examples
* Lists all resources found in the '''tmp''' path of the ''factbook'' database:<br/><code>http://localhost:8984/rest/factbook/tmp</code>
* Returns the number of documents in a database:<br/><code>http://localhost:8984/rest/database?query=count(.)</code>
* Serializes a document as JSONML:<br/><code>http://localhost:8984/rest/factbook/factbook.xml?method=json&json=format=jsonml</code>
==POST Method==
The body of a POST request is interpreted as XML fragment, which specifies theoperation to perform. The name of the root element determines how the body must conform to a given will be evaluated: * {{Code|commands}}: Run [[REST: POST SchemaCommands#Command Scripts|XML SchemaCommand Script]]* {{Code|query}}: Execute XQuery expression* {{Code|run}}: Run server-side file (query or command script)* {{Code|command}}: Execute single command The root element may be bound to the optional REST namespace.Existing command scripts can be sent to the server without any modifications: * Create an empty database and return database information: <syntaxhighlight lang="xml"><commands> <create-db name='db'/> <info-db/></commands></syntaxhighlight> For the other commands, the following child elements are supported: {| class="wikitable"|-! Name! Description|-| {{Code|text}}| Required; contains the query string, command 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 item|}
; Examples
* The following query returns Return the first five city names of the <b>factbook</b> database: <pre classsyntaxhighlight lang="brush:xml"><rest:query xmlns:rest="http://basex.org/rest"> <rest:text><![CDATA[ (//city/name)[position() <= 5] ]]></rest:text></rest:query></presyntaxhighlight>
* 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 classsyntaxhighlight lang="brush:xml"><rest:query xmlns:rest="http://basex.org/rest"> <rest:text>for $i in .//text() return string-length($i)</rest:text> <rest:context>
<xml>
<text>Hello</text>
<text>World</text>
</xml>
</rest:context></rest:query></presyntaxhighlight>
* The following request returns Return the registered database users encoded in <code>ISO-8859-1</code>:<pre classsyntaxhighlight lang="brush:xml"><command xmlns="http://basex.org/rest">
<text>show users</text>
<parameter name='encoding' value='ISO-8859-1'/>
</command>
</presyntaxhighlight>
* This example creates Create a new database from the specified input and retains preserve all whitespaces:<pre classsyntaxhighlight lang="brush:xml"><command xmlns="http://basex.org/rest">
<text>create db test http://files.basex.org/xml/xmark.xml</text>
<option name='chop' value='false'/>
</command>
</presyntaxhighlight>
* The last request runs a Bind value to the {{Code|$person}} variable and run query <code>queryfind-person.xq</code> , which must be located in the directory specified by <code>[[Options#WEBPATH{{Option|WEBPATH]]</code>}}:<pre classsyntaxhighlight lang="brush:xml"><run xmlns> <variable name="http://basex.org'person' value='Johannes Müller'/rest"> <text>queryfind-person.xq</text>
</run>
</presyntaxhighlight>
==PUT Method==
There are two ways to store non-XML data in BaseX:
* '''Store as rawRaw Data''':<br/> If <code>application/octet-stream</code> is chosen as content-type, the input is added as [[Binary Data]].
* '''Convert to XML''':<br/> Incoming data is converted to XML if a parser is available for the specified content-type. The following content types are supported:
** <code>application/json</code>: Stores JSON as XML.
* 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:8984/rest?run=mult.xq&$a=21&$b=2</code>
<pre classsyntaxhighlight lang="brush:xquery">
(: XQuery file: mult.xq :)
declare variable $a as xs:integer external;
declare variable $b as xs:integer external;
<mult>{ $a * $b }</mult>
</presyntaxhighlight>
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 operation, external variables can be specified via the <code><variable/></code> element:
<pre classsyntaxhighlight lang="brush:xml">
<query xmlns="http://basex.org/rest">
<text><![CDATA[
<variable name="b" value="2"/>
</query>
</presyntaxhighlight>
=Response=
<code>org.basex.util.Base64</code> can be used for that purpose:
<pre classsyntaxhighlight lang="brush:java">
import java.net.*;
import org.basex.util.*;
}
}
</presyntaxhighlight>
===Content-Types===
the connection (in this example we explicitly store the input file as raw):
<pre classsyntaxhighlight lang="brush:java">
// store input as raw
conn.setRequestProperty("Content-Type", "application/octet-stream");
</presyntaxhighlight>
See the [[REST#PUT Requests|PUT Requests]] section for a description of the possible content-types.
==Command Line==
Tools such as the Linux commands [httphttps://www.gnu.org/s/wget/ Wget] or [http://curl.haxx.se/ cURL] exist to
perform HTTP requests (try copy & paste):
=Changelog=
;Version 9.0
* Added: Support for command scripts in the [[#POST Method|POST Method]].
* Updated: The REST namespace in the [[#POST Method|POST Method]] has become optional.
;Version 8.1
* 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.
;Version 8.0
;Version 7.2
* Removed: direct Direct evaluation of adresses resources with <code>application/xquery</code> as content type
;Version 7.1.1
;Version 7.0
* REST API introduced, replacing the old JAX-RX API
