administrator, editor
31
edits
Changes
Jump to navigation
Jump to search
m
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 contents of a database can be retrieved by directly addressing the resource: :<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.
With {{Version|9.0}}, The root element may be bound to the optional REST namespace of the root element has become optional.This means, for example, that existing Existing command scripts can be sent to the server without any modifications: * Create an empty database and return database information: <pre class="brush:xml"><commands> <create-db name='db'/> <info-db/></commands></pre>.
* 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"><rest:query xmlns:rest="http://basex.org/rest"> <rest:text><![CDATA[ (//city/name)[position() <= 5] ]]></rest:text></rest:query>
* Return string lengths of all text nodes that are found in the node that has been specified as initial context node: <pre classlang="brush:xml">
* Return the registered database users encoded in <code>ISO-8859-1</code>: <pre classlang="brush:xml">
* Create a new database from the specified input and preserve all whitespaces: <pre classlang="brush:xml">
* Bind value to the {{Code|$person}} variable and run query <code>find-person.xq</code>, which must be located in the directory specified by <code>[[Options#WEBPATH|WEBPATH]]</code>: <pre classlang="brush:xml">
Have Take a look at the [[REST#Usage Examples|usage examples]] for more detailed examples using Java and shell tools like cURL.
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 :)
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 ([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.
=Usage=
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]]).
A web browser can be used to perform simple GET-based REST requests and display the response. Some alternatives for using REST are listed in the [[#Usage Examples|Usage Examples]].
Since BaseX 10, results in the {{Code|rest}} namespace are returned unprefixed:
<pre lang="xml">
<!-- before -->
<rest:databases xmlns:rest="http://basex.org/rest"/>
<!-- BaseX 10 -->
<databases xmlns="http://basex.org/rest"/>
</pre>
=URL Architecture=
A request to the root URL returns all available databases:
The resources of a database can be (directories, resource metadata) are listed by specifying the if a database, and potential sub directories, in the URL.In the given example, a single XML document an optional directory path is stored in the ''factbook'' databasespecified:
:<code>http://localhost:89848080/rest/factbookarticles</code>
<pre classlang="brush:xml"> <rest:database name="factbook" resources="1articles" xmlns:rest="http://basex.org/rest"> <rest:dir>binaries</dir> <resource type="xml" content-type="application/xml" size="77192">factbook1973-02-08-xltp325.xml</rest:resource> ...</rest:database></pre> If the path to a single resource is specified, the resource itself will be returned:
==Parameters==
==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 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 {{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.
; Examples
* 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 JSONMLJsonML:<br/><code>http://localhost:89848080/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:89848080/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:89848080/rest?command=show+users</code>
==POST Method==
The name of the root element determines how the body will be evaluated:
* {{Code|commands}} (new since {{Version|9.0}}): Run [[Commands#Command Scripts|Command Script]]
* {{Code|query}}: Execute XQuery expression
* {{Code|run}}: Run server-side file (query or command script)
* {{Code|command}}: Execute single command
For the other commands, the following child elements are supported:
; Examples
</pre>
<query>
<text>for $i in .//text() return string-length($i)</text>
</pre>
<command>
<text>show users</text>
</pre>
<command>
<text>create db test http://files.basex.org/xml/xmark.xml</text>
</pre>
<run>
<variable name='person' value='Johannes Müller'/>
; Examples
* 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).
==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: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>
The HTTP status code <code>404</code> is returned if no database is specified.
==GET Method==
; Example
declare variable $a as xs:integer external;
declare variable $b as xs:integer external;
<mult>{ $a * $b }</mult>
</pre>
; Example
{{Announce|Updated with Version 11:}} Support for multiple values.
The request <code>http://localhost:8080/rest?run=sum&n=3&n=4&n=5</code> assigns multiple values to the same variable:
<pre lang='xquery'>
(: XQuery file: sum.xq :)
declare variable $n as xs:integer* external;
sum($n)
</pre>
==POST Method==
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">
<query xmlns="http://basex.org/rest">
<text><![CDATA[
declare variable $x a as xs:integer external; declare variable $y b as xs:integer external;
<mult>{ $a * $b }</mult>
]]></text>
The following three example requests all return <code><a/></code> with <code>application/xml</code> as content-type:
:<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>
=Usage Examples=
<code>org.basex.util.Base64</code> can be used for that purpose:
<pre classlang="brush:java">
import java.net.*;
import org.basex.util.*;
public static void main(String[] args) throws Exception {
// The java URL connection to the resource.
URL url = new URL("http://localhost:89848080/rest/factbook");
// Establish the connection to the URL.
String user = "bob";
String pw ="alice";
// Encode user name username and password pair with a base64 implementation.
String encoded = Base64.encode(user + ":" + pw);
// Basic access authentication header to connection request.
the connection (in this example we explicitly store the input file as raw):
<pre classlang="brush:java">
// store input as raw
conn.setRequestProperty("Content-Type", "application/octet-stream");
==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):
;GET
* <code><nowiki>curl -i "http://localhost:89848080/rest/factbook?query=//city/name"</nowiki></code>
;POST
* <code><nowiki>curl -i -X POST -H "Content-Type: application/xml" -d "<query xmlns='http://basex.org/rest'><text>//city/name</text></query>" "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>
;PUT
* <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>
;DELETE
* <code><nowiki>curl -i -X DELETE "http://admin:admin@localhost:89848080/rest/factbook"</nowiki></code>
=Changelog=
;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.
;Version 10.0
* Updated: Results in the {{Code|rest}} namespace will be returned unprefixed.
* Updated: {{Code|dir}} elements are returned when listing the contents of a database.
;Version 9.0
;Version 8.1
* Added: Support for input-specific content-type parameters
* Updated: The [[#GET Method|run operation]] now resolves file paths against the [[Options#RESTPATH{{Option|RESTPATH]] }} option.
;Version 8.0
