From BaseX Documentation
Revision as of 16:43, 16 March 2012 by Arve (talk | contribs) (first draft version)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

Get a fresh copy of basex-api from our github repositories. It contains the base server architecure. Refer to BaseX HTTP Server for details.

To start the server, there are two possibilities.

  • Inside the basex-api directory run the command mvn jetty:run. (stop with CTRL + C)
  • Run the script etc/basexhttp (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 src/main/webapp.

Server configuration

With the first serverrun a configuration file will be put to the serverroot (by default src/main/webapp/.basex). Other configurations may be done within src/main/webapp/WEB-INF/web.xml.

E.G. in .basex pathes for database (variable DBPATH), RESTfulXQ modules (variable HTTPPATH) and BaseX Package repository (variable REPOPATH) 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 % 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.

 : A simple module with REST-annotations
module namespace hw = '';
declare namespace rest-hw = '';

function hw:demo($path as xs:string) as document-node() {
		Hello World! You accessed the path {$path}.

If you accessed the server at localhost:8984/restxq/demo-module you would see

	Hello World! You accessed the path demo-module.

RESTful Annotations

A List of all implemented annotations. As sample namespace for REST annotations rest is used.

Path Annotation (constraint)

%rest:path("/a/path/{$with}/some/{$variable}") 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.

A function is allowed to have at least one path annotation.

HTTP Method Annotations (constraints)

  • Simple Method Annotations

%rest:GET %rest:HEAD %rest:DELETE

  • Content Method Annotations

%rest:POST %rest:POST("{$post-body}") %rest:PUT %rest:PUT("{$put-body}")

Media Type Annotations (constraint)

  • HTTP Content Type

%rest:consumes() one or more media-types as string. e.g. %rest:consumes("application/xml", "text/xml")

  • HTTP Accept

%rest:produces() one media-type as string. e.g. %rest:produces("application/atom+xml")

These default to */*, if no media-type annotations are given.

Query String Annotations (Parameter)

%rest:query-param() Assigns first parameter to the variable in second parameter if found in the Query String. As optional third parameter 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.


  • %rest:query-param("parameter", "{$value}", "default")
  • %rest:query-param("answer", "{$answer}", 42)
  • %rest:query-param("search", "{$search-param}")

HTML Form field Annotations (Parameter)

%rest:form-param() same usage as #Query String Annotations (Parameter), but extracted from POST or GET.

HTTP Header Annotations (Parameter)

%rest:header-param() same usage as #Query String Annotations (Parameter), but extracted from HTTP Header.


  • %rest:header-param("User-Agent","{$user-agent}")
  • %rest:header-param("Referer","{$referer}", "none")

Cookie Annotations (Parameter)

%rest:cookie-param() same usage as #Query String Annotations (Parameter), but extracted from Cookie.


  • %rest:cookie-param("username","{$user}")
  • %rest:cookie-param("authentication","{$auth}", "no_auth")