Changes

This page is part of the [[Developer Section]]. It describes how to use the RESTfulXQ API RESTXQ of BaseX. At XML Prague Conference 2012, Adam Retter introduced RESTfulXQ. It adds webapplication development power to XQuery. As of {{Version|7.2}} RESTfulXQ is supported by BaseX.

First of all, launch the [[Startup#BaseX HTTP Server|BaseX HTTP Server]], which will itself start an instance of the [http://jetty.codehaus.org/jetty/ Jetty WebServer], which listens to the port <!code>8984</code> by default (check out the additional [[Startup Options#BaseX HTTP Server|command-- TODO add how to run without github package -->line options]]).

By default, the HTTP Server will be accessible at http://localhost:8984.<!-- [CG] I guess we need another general page on the HTTP Server and the Servlet that summarizes all this information...Get a fresh copy of [https://github.com/basexdb/basex-api basex-api] from our github repositories. It contains the base server architecurearchitecture. Refer to [[Startup#BaseX HTTP Server|BaseX HTTP Server]] for details.

To start the serverHTTP Server, there are two possibilities. * Inside the basex-api directory run the command <code>mvn jetty:run</code>. (stop with <code>CTRL + C</code>)* Run the script <code>etc/basexhttp</code> (inside basex-api package). There is a script to stop the server, located in the same folder. By default the server will be accessible at http://localhost:8984/. The serverroot is <code>src/main/webapp</code>.

E.GIf the server is started as Servlet, the {{Mono|. basex}} configuration file will be stored in <code>the root of the web directory.basex<(usually {{Mono|src/main/code> pathes for database (variable <code>DBPATH<webapp/code>}}). The .basex file contains all [[Options#Main Options|Main Options]], such as the path to the database, RESTfulXQ modules (variable <code>HTTPPATH</code>) the HTTP directory and the [[Packaging | BaseX PackageRepository]] repository (variable <code>REPOPATH<. Initial configuration options can be adjusted in the {{Mono|src/main/webapp/WEB-INF/code>) are declaredweb.xml}} file.

All RESTfulXQ modules can be accessed at <pre class="brush:xquery">(:~ A simple module with REST-annotations :)module namespace hw = 'http://localhost:8984basex.org/modules/restxq/. It follows instructions on how to write such a module.-demo';

To a regular model you add a namespace for REST annotations. With <code>%</code> followed by the namespace one applies REST annotations to existing functions. These annotations define when a modules function should be invoked and with what arguments. <pre class="brush:xquery">(:~ : A simple module with REST-annotations :)module namespace hw = 'http://basex.org/modules/restxq-demo';declare namespace rest-hw = 'http://exquery.org/ns/rest/annotation';

%rest-hw:path("{$path}") %output:media-type("application/xml")

&lt;xml&gt; Hello World! You accessed the path {$path}. &lt;/xml&gt;

If you accessed the server at URI {{Mono|localhost:8984/restxq/demo-module you would see}} is accessed, the result will be

Hello World! You accessed the path demo-module.