REST - Revision history

Andy Bunce at 14:00, 17 April 2024

2024-04-17T14:00:09Z

Andy Bunce at 13:58, 17 April 2024

2024-04-17T13:58:39Z

CG: Text replacement - "syntaxhighlight" to "pre"

2023-12-01T16:38:29Z

Text replacement - "syntaxhighlight" to "pre"

CG: Text replacement - "" to ""

2023-12-01T16:36:03Z

Text replacement - "</syntaxhighlight>" to "</pre>"

CG: Text replacement - "" to "

2023-12-01T16:33:31Z

Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>"

CG: /* GET Method */

2023-11-03T14:56:28Z

GET Method

CG at 14:42, 3 November 2023

2023-11-03T14:42:24Z

CG at 14:41, 3 November 2023

2023-11-03T14:41:54Z

CG: /* POST Method */

2023-11-03T14:32:42Z

POST Method

CG: /* DELETE Method */

2023-11-03T14:31:46Z

DELETE Method

@@ Line 15: / Line 15: @@
 <rest:databases xmlns:rest="http://basex.org/rest"/>
-<!-- now -->
+<!-- BaseX 10 -->
 <databases xmlns="http://basex.org/rest"/>
 </pre>

@@ Line 15: / Line 15: @@
 <rest:databases xmlns:rest="http://basex.org/rest"/>
-<!-- before -->
+<!-- now -->
 <databases xmlns="http://basex.org/rest"/>
 </pre>

@@ Line 11: / Line 11: @@
 Since BaseX 10, results in the {{Code|rest}} namespace are returned unprefixed:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <!-- before -->
 <rest:databases xmlns:rest="http://basex.org/rest"/>
@@ Line 25: / Line 25: @@
 :<code>http://localhost:8080/rest</code>
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <databases xmlns="http://basex.org/rest">
    <database resources="25742" size="43813599">articles</database>
@@ Line 36: / Line 36: @@
 :<code>http://localhost:8080/rest/articles</code>
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <database name="articles" xmlns="http://basex.org/rest">
    <dir>binaries</dir>
@@ Line 116: / Line 116: @@
 Create an empty database and return database information:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <commands>
    <create-db name='db'/>
@@ Line 125: / Line 125: @@
 Return the first five city names of the <b>factbook</b> database:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <rest xmlns="http://basex.org/rest">
    <rest><![CDATA[ (//city/name)[position() <= 5] ]]></text>
@@ Line 133: / Line 133: @@
 Return string lengths of all text nodes that are found in the node that has been specified as initial context node:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <query>
    <text>for $i in .//text() return string-length($i)</text>
@@ Line 147: / Line 147: @@
 Return the registered database users encoded in <code>ISO-8859-1</code>:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <command>
    <text>show users</text>
@@ Line 156: / Line 156: @@
 Create a new database from the specified input and preserve all whitespaces:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <command>
    <text>create db test http://files.basex.org/xml/xmark.xml</text>
@@ Line 165: / Line 165: @@
 Bind value to the {{Code|$person}} variable and run query <code>find-person.xq</code>:
-<syntaxhighlight lang="xml">
+<pre lang="xml">
 <run>
    <variable name='person' value='Johannes Müller'/>
@@ Line 246: / Line 246: @@
 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 lang="xml">
+<pre lang="xml">
 <query xmlns="http://basex.org/rest">
    <text><![CDATA[
@@ Line 298: / Line 298: @@
 <code>org.basex.util.Base64</code> can be used for that purpose:
-<syntaxhighlight lang="java">
+<pre lang="java">
 import java.net.*;
 import org.basex.util.*;
@@ Line 334: / Line 334: @@
 the connection (in this example we explicitly store the input file as raw):
-<syntaxhighlight lang="java">
+<pre lang="java">
 // store input as raw
 conn.setRequestProperty("Content-Type", "application/octet-stream");

@@ Line 17: / Line 17: @@
 <!-- before -->
 <databases xmlns="http://basex.org/rest"/>
-</syntaxhighlight>
+</pre>
 =URL Architecture=
@@ Line 30: / Line 30: @@
    ...
 </databases>
-</syntaxhighlight>
+</pre>
 The resources of a database (directories, resource metadata) are listed if a database and an optional directory path is specified:
@@ Line 42: / Line 42: @@
    ...
 </database>
-</syntaxhighlight>
+</pre>
 If the path to a single resource is specified, the resource itself will be returned:
@@ Line 121: / Line 121: @@
    <info-db/>
 </commands>
-</syntaxhighlight>
+</pre>
 Return the first five city names of the <b>factbook</b> database:
@@ Line 129: / Line 129: @@
    <rest><![CDATA[ (//city/name)[position() <= 5] ]]></text>
 </rest>
-</syntaxhighlight>
+</pre>
 Return string lengths of all text nodes that are found in the node that has been specified as initial context node:
@@ Line 143: / Line 143: @@
    </context>
 </query>
-</syntaxhighlight>
+</pre>
 Return the registered database users encoded in <code>ISO-8859-1</code>:
@@ Line 152: / Line 152: @@
    <parameter name='encoding' value='ISO-8859-1'/>
 </command>
-</syntaxhighlight>
+</pre>
 Create a new database from the specified input and preserve all whitespaces:
@@ Line 161: / Line 161: @@
    <option name='chop' value='false'/>
 </command>
-</syntaxhighlight>
+</pre>
 Bind value to the {{Code|$person}} variable and run query <code>find-person.xq</code>:
@@ Line 170: / Line 170: @@
    <text>find-person.xq</text>
 </run>
-</syntaxhighlight>
+</pre>
 ==PUT Method==
@@ Line 227: / Line 227: @@
 declare variable $b as xs:integer external;
 <mult>{ $a * $b }</mult>
-</syntaxhighlight>
+</pre>
 ; Example
@@ Line 238: / Line 238: @@
 declare variable $n as xs:integer* external;
 sum($n)
-</syntaxhighlight>
+</pre>
 The dollar sign can be omitted as long as the variable name does not equal a parameter keyword (e.g.: <code>method</code>).
@@ Line 256: / Line 256: @@
    <variable name="b" value="2"/>
 </query>
-</syntaxhighlight>
+</pre>
 =Response=
@@ Line 327: / Line 327: @@
+   }
+}
-</syntaxhighlight>
+</pre>
 ===Content-Types===
@@ Line 337: / Line 337: @@
 // store input as raw
 conn.setRequestProperty("Content-Type", "application/octet-stream");
-</syntaxhighlight>
+</pre>
 See the [[REST#PUT Requests|PUT Requests]] section for a description of the possible content-types.

@@ Line 222: / Line 222: @@
 The request <code>http://localhost:8080/rest?run=multiply&a=21&b=2</code> assigns two variables and invokes <code>multiply.xq</code>:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 (: XQuery file: multiply.xq :)
 declare variable $a as xs:integer external;
@@ Line 234: / Line 234: @@
 The request <code>http://localhost:8080/rest?run=sum&n=3&n=4&n=5</code> assigns multiple values to the same variable:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 (: XQuery file: sum.xq :)
 declare variable $n as xs:integer* external;

← Older revision		Revision as of 14:42, 3 November 2023
Line 363:		Line 363:

	;Version 11.0		;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.		* Updated: [[#Assigning Variables\|Assigning Variables]]: Support for multiple values.

@@ Line 1: / Line 1: @@
 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.
+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 methods GET, PUT, DELETE, and POST can be used to interact with the database.
 =Usage=
@@ Line 66: / Line 63: @@
 ==GET Method==
-If the GET method is used, all query parameters are directly specified within the URL.
+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.
+* {{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 JsonML:<br/><code>http://localhost:8080/rest/factbook/factbook.xml?method=json&json=format=jsonml</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>
 ==POST Method==
@@ Line 206: / Line 198: @@
 * 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)
+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 specified database was not found) or <code>400</code> (if the operation could not be completed).
-Have a look at the [[REST#Usage Examples|usage examples]] for more detailed examples using Java and shell tools like cURL.
+Take a look at the [[REST#Usage Examples|usage examples]] for more detailed examples using Java and shell tools like cURL.
 ==DELETE Method==

@@ Line 96: / Line 96: @@
 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:
@@ Line 130: / Line 121: @@
 ; Examples
 Return the first five city names of the <b>factbook</b> database:

@@ Line 218: / Line 218: @@
 The DELETE method is used to delete databases or resources within a database.
-; Example
+; Examples
 * 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>