RESTXQ

This page is part of the Developer Section. It describes how to use RESTXQ of BaseX.

RESTXQ, specified by Adam Retter, is a new API that facilitates the use of XQuery as a Server Side processing language for the Web whilst maintaining portability. It has been largely inspired by Java’s JAX-RS API, and it defines a pre-defined set of XQuery 3.0 annotations for mapping HTTP requests to XQuery functions. As of Version 7.2, RESTXQ is supported by BaseX.

Getting started

First of all, launch the BaseX HTTP Server, which will itself start an instance of the Jetty WebServer, which listens to the port 8984 by default (check out the additional command-line options).

By default, the HTTP Server will be accessible at http://localhost:8984.

Server configuration

If the server is started as Servlet, the .basex configuration file will be stored in the root of the web directory. (usually src/main/webapp/). The .basex file contains all Main Options, such as the path to the database, the HTTP directory and the Package Repository. Initial configuration options can be adjusted in the src/main/webapp/WEB-INF/web.xml file.

RESTXQ Modules

All RESTXQ modules can be accessed at http://localhost:8984/restxq/. Some instructions on how to write such a module follow:

A regular module contains a declaration to the rest namespace http://exquery.org/ns/rest/annotation. So-called REST annotations are introduced with the annotation character %, followed by the declared rest prefix. These annotations define when a modules function will be invoked and which values will be bound to its arguments.

(:~ A simple module with REST-annotations :)
module namespace hw = 'http://basex.org/modules/restxq-demo';

declare namespace rest = 'http://exquery.org/ns/rest/annotation';

declare
  %rest: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>
};

If the URI localhost:8984/restxq/demo-module is accessed, the result will be

<xml>
  Hello World! You accessed the path demo-module.
</xml>

Annotations

This section lists all annotations provided by RESTXQ. rest is used as namespace prefix.

Constraints

Constraints restrict the service requests that a resource function may process.

Paths

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

• 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 Types

• 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.

Parameters

Parameters are optional annotations that can be used to bind additional values to function arguments:

Query Strings

%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.

Examples

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

HTML Form Fields

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

HTTP Headers

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

Examples

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

Cookies

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

Examples

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

References

RESTXQ has been proposed by Adam Retter. The following documents are currently available:

• RESTful XQuery, Standardised XQuery 3.0 Annotations for REST, XMLPrague 2012
• RESTXQ, MarkLogic User Group London, 2012