RESTXQ

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

RESTXQ, introduced by Adam Retter, is a new API that facilitates the use of XQuery as a Server Side processing language for the Web. RESTXQ has been inspired by Java’s JAX-RS API: it defines a pre-defined set of XQuery 3.0 annotations for mapping HTTP requests to XQuery functions, which in turn generate and return HTTP responses. 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 RESTXQ service is available via http://localhost:8984/restxq/. 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. The initial configuration options can be adjusted in the src/main/webapp/WEB-INF/web.xml file.

Module Declarations

A RESTXQ module must contain a declaration to the namespace http://exquery.org/ns/rest/annotation. A Resource Function is an XQuery function that has been marked up with RESTXQ annotations (annotations will be introduced with the upcoming XQuery 3.0 standard). When an HTTP request comes in, a resource function will be invoked that matches the constraints indicated by its annotations.

A simple RESTXQ module is shown below:

(:~ 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) {
  <xml>
    Hello World! You accessed the path { $path }.
  </xml>
};

If the URI http://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 HTTP requests that a resource function may process.

Paths

A resource function must have a single Path Annotation. It will be called if a URL matches the path segments and templates specified as argument. Path templates contain variables in curly brackets, and map path values to arguments of the function. The following example represents a path annotation with three segments and two templates:

declare %rest:path("/a/path/{$with}/some/{$variable}")
       function($with, $variable) { ... };

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}")

Content Types

• HTTP Content Types: One or more media-types may be specified as strings, e.g.:
  

%rest:consumes("application/xml", "text/xml")

• HTTP Accept: One or more media-types may be specified as strings, 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

The value of the first parameter, if found in the Query String, will be assigned to the variable specified as second parameter. Optionally, a third parameter may be specified as default:

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

HTML Form Fields

Form parameters are specified the same way as query strings. Their values are extracted from GET or POST requests.

%rest:form-param("parameter", "{$value}", "default")

HTTP Headers

Header parameters are specified the same way as query strings:

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

Cookies

Cookie parameters are specified the same way as query strings:

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

References

RESTXQ has been proposed by Adam Retter. More information on all specifics can be found in the following two documents:

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