Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
==Operations==
GET and POST requests support the following '''operations''':
* '''Query''':<br/>Evaluates an XPath/XQuery expression. If a database or database path is specified in the URL, it is used as initial query context.
* '''Run''':<br/>Runs a query file located on the server. The query directory is defined by the <code>[[Options#WEBPATH|WEBPATH]]</code> option.
* '''Command''':<br/>Executes a [[Commands|database command]].
* '''Get''':<br/>This is the default operation for the GET operation (it is not possible to use this operation in a POST request). It returns a list of all databases, the resources of a database or the addressed resource.
Additionally, the The following '''parameters''' can be applied to the operations:
* '''Wrap''':<br/>The <code>wrap</code> parameter encloses all query results with XML elements, using the <code>http://basex.org/rest</code> namespace.
* The last example includes an to disallow [[Options#XQUERY3|XQuery 3.0]] expressions:<br/><code>http://localhost:8984/rest?query=12345&xquery3=false</code>POST Method==
==The body of a POST Requests==request is interpreted as XML fragment, which specifies the operation to perform.The name of the root element determines how the body will be evaluated:
** <code>application/jsonml+json</code>: Stores JSONML input as XML.
#* <code>raw</code> → <code>application/octet-stream</code>
[[Category:Server]]
[[Category:HTTP]]
[[Category:Developer]]
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 distributed XML database resourcesvia URLs.
REST ([http://en.wikipedia.org/wiki/Representational_State_Transfer REpresentational State Transfer])
facilitates a simple and fast access to databases through HTTP. The HTTP methods
=Usage=
By default, REST services are available at {{Code|http://localhost:8984/rest/}}. If no default credentials are specified in the URL or when starting the web application, and they will be requested by the HTTP server is started with admin credentials 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]].
If a resource is not found, an HTTP response will be generated with <code>404</code> as status code.
==Parameters==
* '''Variables''':<br/>External variables can be ''bound'' before a query is evaluated ([[REST#Assigning Variables|see below]] for more).
* '''Options''':<br/>Specified [[Options]] are applied before the actual operation will be performed.
* '''Serialization''':<br/>All [[Serialization]] parameters known to BaseX can be specified as query parameters. Parameters that are specified within a query will be interpreted by the REST server before the output is generated.
While '''Options''' can be specified for all operations, the remaining parameters will only make sense for '''Query''' and '''Run'''.
=Request Methods=
==GET RequestsMethod==
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 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|RESTPATH]]</code> (before, it was resolved against <code>[[Options#WEBPATH|WEBPATH]]</code>).
; Examples
* The first example lists Lists all resources found in the '''tmp''' path of the ''factbook'' database:<br/><code>http://localhost:8984/rest/factbook/tmp</code>
* The first example prints the city names from the ''factbook'' database and encloses all results with Serializes a <code><rest:result/></code> elementsdocument as JSONML:<br/><code>http://localhost:8984/rest/factbook/factbook.xml?querymethod=//city/namejson&wrapjson=format=yesjsonml</code>
* In the next request, <code>US-ASCII</code> is chosen as output encoding, and the query <code>eval.xq</code> is evaluated:<br/><code>http://localhost:8984/rest?run=eval.xq&encoding=US-ASCII</code>
* The next URL turns on XML wrapping and lists all database users that are known to BaseX:<br/><code>http://localhost:8984/rest?command=show+users</code>
* {{Code|commands}}: 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 The body of a POST request is interpreted as XML fragmentroot 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: <pre class="brush:xml"><commands> <create-db name='db'/> <info-db/></commands></pre> For the other commands, which specifies thefollowing child elements are supported: {| class="wikitable"|-! Name! Description|-| {{Code|text}}operation | Required; contains the query string, command string, or file to perform. The body must conform to a given [[REST: POST Schemabe 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|XML Schema]].}
; Examples
* The following query returns Return the first five city names of the <b>factbook</b> database:
<pre class="brush:xml">
<rest:query xmlns:rest="http://basex.org/rest"> <rest:text><![CDATA[ (//city/name)[position() <= 5] ]]></rest:text></rest:query>
</pre>
* 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 class="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>
</pre>
* The following request returns Return the registered database users encoded in <code>ISO-8859-1</code>:
<pre class="brush:xml">
<command xmlns="http://basex.org/rest">
<text>show users</text>
<parameter name='encoding' value='ISO-8859-1'/>
</pre>
* This example creates Create a new database from the specified input and retains preserve all whitespaces:
<pre class="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'/>
</pre>
* 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|WEBPATH]]</code>:
<pre class="brush:xml">
<run xmlns> <variable name="http://basex.org'person' value='Johannes Müller'/rest"> <text>queryfind-person.xq</text>
</run>
</pre>
==PUT RequestsMethod==
The PUT method is used to create new databases, or to add or update existing database resources:
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 data is added as raw[[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.
** <code>text/plain</code>: Stores plain text input as XML.
** <code>text/comma-separated-values</code>: Stores CSV text input as XML.
** <code>text/html</code>: Stores HTML input as XML.
Conversion can be influenced by specifying additional content-type parameters (see [[RESTXQ#Content Types|RESTXQ]] for more information).
If raw data is added and if no content type, or a wrong content, is specified, a <code>400</code> (BAD REQUEST) error will be raised.
Have a look at the [[REST#Usage Examples|usage examples]] for more detailed examples using Java and shell tools like cURL.
==DELETE RequestsMethod==
The DELETE method is used to delete databases or resources within a database.
=Assigning Variables=
==GET RequestsMethod==
All query parameters that have not been processed before will be treated as variable assignments:
The dollar sign can be omitted as long as the variable name does not equal a parameter keyword (e.g.: <code>method</code>).
==POST RequestsMethod==
If <code>query</code> or <code>run</code> is used as operation, external variables can be specified via the <code><variable/></code> element:
</pre>
=Response= ==Content Type==
As the content type of a REST response cannot necessarily be dynamically determined in all cases, it can be manually adjusted enforced by the user. The final content type of a REST response is chosen in several stepsas follows:
# By default, If the content type of a response depends on the chosen operation:#* '''Query'''/'''Run''' → serialization parameter <code>application/xml</code>#* '''Command''' → <code>text/plain</code>#* '''Get''' → <code>application/xml[[Serialization|media-type]]</code>is supplied, or it will be adopted as content -type of the addressed resource.# The default content type is overwritten Otherwise, if a the serialization parameter <code>[[Serialization|serialization method]] </code> is specifiedsupplied, either as [[#Parameters|query parameters]] or within the XQuery expression. The following method/content-type mappings are availablewill be chosen according to the following mapping:#* <code>xml</code>, <code>adaptive</code>, <code>basex</code> → <code>application/xml</code>
#* <code>xhtml</code> → <code>text/html</code>
#* <code>html</code> → <code>text/html</code>
#* <code>text</code> → <code>text/plain</code>
#* <code>json</code> → <code>application/json</code>
# The If no media-type or serialization method is supplied, the content type is overwritten in any case if of a specific response depends on the chosen REST operation:#* '''Query'''/'''Run''' → <code>application/xml</code>#* '''Command''' → <code>text/plain</code>#* '''Get''' → <code>application/xml</code>, or content type of the addressed resource Serialization parameters can either be supplied as [[Serialization#Parameters|media-typequery parameters]] is chosen, again as query parameter or within the query.
The following three example requests will all return <code><a/></code> as result and use with <code>application/xml</code> as content-type:
:<code>http://localhost:8984/rest?query=%3Ca/%3E</code><br/><code>http://localhost:8984/rest?query=%3Ca/%3E&method=xml</code><br/><code>http://localhost:8984/rest?query=%3Ca/%3E&media-type=application/xml</code>
=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 for input-specific content-type parameters
* Updated: The [[#GET Method|run operation]] now resolves file paths against the [[Options#RESTPATH|RESTPATH]] option.
;Version 8.0
* Removed: {{Code|wrap}} parameter
;Version 7.9
* Updated: Also evaluate command scripts via the <code>[[#GET Method|run]]</code> operation.
;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
