editor, reviewer
115
edits
Changes
Jump to navigation
Jump to search
first draft version
This page is part of the [[Developer Section]]. It describes how to use the RESTfulXQ API 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.
=Getting started=
<!-- TODO add how to run without github package -->
Get a fresh copy of [https://github.com/basexdb/basex-api basex-api] from our github repositories. It contains the base server architecure. Refer to [[Startup#BaseX HTTP Server|BaseX HTTP Server]] for details.
To start the 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>.
=Server configuration=
With the first serverrun a configuration file will be put to the serverroot (by default <code>src/main/webapp/.basex</code>). Other configurations may be done within
<code>src/main/webapp/WEB-INF/web.xml</code>.
E.G. in <code>.basex</code> pathes for database (variable <code>DBPATH</code>), RESTfulXQ modules (variable <code>HTTPPATH</code>) and [[Packaging | BaseX Package]] repository (variable <code>REPOPATH</code>) are declared.
=RESTfulXQ Modules=
All RESTfulXQ modules can be accessed at http://localhost:8984/restxq/. It follows instructions on how to write such a module.
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';
declare
%rest-hw:path("{$path}")
%output:media-type("application/xml")
function hw:demo($path as xs:string) as document-node() {
<xml>
Hello World! You accessed the path {$path}.
</xml>
};</pre>
If you accessed the server at localhost:8984/restxq/demo-module you would see
<pre class="brush:xml"><xml>
Hello World! You accessed the path demo-module.
</xml></pre>
=RESTful Annotations=
A List of all implemented annotations. As sample namespace for REST annotations <code>rest</code> is used.
==Path Annotation (constraint)==
<code>%rest:path("/a/path/{$with}/some/{$variable}")</code>
if url matches the given pattern, variables (in curly brackets) will be assigned. The variables serve as input arguments for the function. The type will be converted, as defined by the function.
<!-- TODO how matching works -->
A function is allowed to have <strong>at least one</strong> path annotation.
==HTTP Method Annotations (constraints)==
* Simple Method Annotations
%rest:GET
%rest:HEAD
%rest:DELETE
<!-- TODO add some descripton -->
* Content Method Annotations
%rest:POST
%rest:POST("{$post-body}")
%rest:PUT
%rest:PUT("{$put-body}")
<!-- TODO add some descripton -->
==Media Type Annotations (constraint)==
* HTTP Content Type
<code>%rest:consumes()</code> one or more media-types as string. e.g. <code>%rest:consumes("application/xml", "text/xml")
* HTTP Accept
<code>%rest:produces()</code> one media-type as string. e.g. <code>%rest:produces("application/atom+xml")</code>
These default to <code>*/*</code>, if no media-type annotations are given.
==Query String Annotations (Parameter)==
<code>%rest:query-param()</code>
Assigns <em>first parameter</em> to the variable in <em>second parameter</em> if found in the [http://en.wikipedia.org/wiki/Query_string Query String]. As optional <em>third parameter</em> a default value may be given. Is no default set and the parameter not contained in the Query-String, the REST annotation will be ignored.
The variable will be type-casted to match the function declaration.
Examples
* <code>%rest:query-param("parameter", "{$value}", "default")</code>
* <code>%rest:query-param("answer", "{$answer}", 42)</code>
* <code>%rest:query-param("search", "{$search-param}")</code>
==HTML Form field Annotations (Parameter)==
<code>%rest:form-param()</code>
same usage as [[#Query String Annotations (Parameter)]], but extracted from POST or GET.
<!-- TODO remark on file submission -->
==HTTP Header Annotations (Parameter)==
<code>%rest:header-param()</code>
same usage as [[#Query String Annotations (Parameter)]], but extracted from HTTP Header.
Examples
* <code>%rest:header-param("User-Agent","{$user-agent}")</code>
* <code>%rest:header-param("Referer","{$referer}", "none")</code>
==Cookie Annotations (Parameter)==
<code>%rest:cookie-param()</code>
same usage as [[#Query String Annotations (Parameter)]], but extracted from Cookie.
Examples
* <code>%rest:cookie-param("username","{$user}")</code>
* <code>%rest:cookie-param("authentication","{$auth}", "no_auth")</code>
[[Category:Server]]
[[Category:Developer]]
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.
=Getting started=
<!-- TODO add how to run without github package -->
Get a fresh copy of [https://github.com/basexdb/basex-api basex-api] from our github repositories. It contains the base server architecure. Refer to [[Startup#BaseX HTTP Server|BaseX HTTP Server]] for details.
To start the 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>.
=Server configuration=
With the first serverrun a configuration file will be put to the serverroot (by default <code>src/main/webapp/.basex</code>). Other configurations may be done within
<code>src/main/webapp/WEB-INF/web.xml</code>.
E.G. in <code>.basex</code> pathes for database (variable <code>DBPATH</code>), RESTfulXQ modules (variable <code>HTTPPATH</code>) and [[Packaging | BaseX Package]] repository (variable <code>REPOPATH</code>) are declared.
=RESTfulXQ Modules=
All RESTfulXQ modules can be accessed at http://localhost:8984/restxq/. It follows instructions on how to write such a module.
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';
declare
%rest-hw:path("{$path}")
%output:media-type("application/xml")
function hw:demo($path as xs:string) as document-node() {
<xml>
Hello World! You accessed the path {$path}.
</xml>
};</pre>
If you accessed the server at localhost:8984/restxq/demo-module you would see
<pre class="brush:xml"><xml>
Hello World! You accessed the path demo-module.
</xml></pre>
=RESTful Annotations=
A List of all implemented annotations. As sample namespace for REST annotations <code>rest</code> is used.
==Path Annotation (constraint)==
<code>%rest:path("/a/path/{$with}/some/{$variable}")</code>
if url matches the given pattern, variables (in curly brackets) will be assigned. The variables serve as input arguments for the function. The type will be converted, as defined by the function.
<!-- TODO how matching works -->
A function is allowed to have <strong>at least one</strong> path annotation.
==HTTP Method Annotations (constraints)==
* Simple Method Annotations
%rest:GET
%rest:HEAD
%rest:DELETE
<!-- TODO add some descripton -->
* Content Method Annotations
%rest:POST
%rest:POST("{$post-body}")
%rest:PUT
%rest:PUT("{$put-body}")
<!-- TODO add some descripton -->
==Media Type Annotations (constraint)==
* HTTP Content Type
<code>%rest:consumes()</code> one or more media-types as string. e.g. <code>%rest:consumes("application/xml", "text/xml")
* HTTP Accept
<code>%rest:produces()</code> one media-type as string. e.g. <code>%rest:produces("application/atom+xml")</code>
These default to <code>*/*</code>, if no media-type annotations are given.
==Query String Annotations (Parameter)==
<code>%rest:query-param()</code>
Assigns <em>first parameter</em> to the variable in <em>second parameter</em> if found in the [http://en.wikipedia.org/wiki/Query_string Query String]. As optional <em>third parameter</em> a default value may be given. Is no default set and the parameter not contained in the Query-String, the REST annotation will be ignored.
The variable will be type-casted to match the function declaration.
Examples
* <code>%rest:query-param("parameter", "{$value}", "default")</code>
* <code>%rest:query-param("answer", "{$answer}", 42)</code>
* <code>%rest:query-param("search", "{$search-param}")</code>
==HTML Form field Annotations (Parameter)==
<code>%rest:form-param()</code>
same usage as [[#Query String Annotations (Parameter)]], but extracted from POST or GET.
<!-- TODO remark on file submission -->
==HTTP Header Annotations (Parameter)==
<code>%rest:header-param()</code>
same usage as [[#Query String Annotations (Parameter)]], but extracted from HTTP Header.
Examples
* <code>%rest:header-param("User-Agent","{$user-agent}")</code>
* <code>%rest:header-param("Referer","{$referer}", "none")</code>
==Cookie Annotations (Parameter)==
<code>%rest:cookie-param()</code>
same usage as [[#Query String Annotations (Parameter)]], but extracted from Cookie.
Examples
* <code>%rest:cookie-param("username","{$user}")</code>
* <code>%rest:cookie-param("authentication","{$auth}", "no_auth")</code>
[[Category:Server]]
[[Category:Developer]]
