Difference between revisions of "RESTXQ"

From BaseX Documentation
Jump to navigation Jump to search
Line 11: Line 11:
 
=Getting started=
 
=Getting started=
  
First of all, launch the BaseX as [[Web Application]]. By default, [http://jetty.codehaus.org/jetty/ Jetty] is used as web server. All HTTP services will be available on port <code>8984</code>, and the RESTXQ service is accessible at {{Mono|http://localhost:8984/restxq/}}.
+
First of all, launch the BaseX as [[Web Application]]. By default, [http://jetty.codehaus.org/jetty/ Jetty] is used as web server. All HTTP services will be available on port <code>8984</code>, and the RESTXQ service is accessible at {{Mono|http://localhost:8984/restxq/}}. If the server is started as servlet, all [[Options#Main Options|Main Options]] (such as the path to the database) can be configured in the {{Mono|web.xml}} file. If run as a standalone application, the settings are stored in the file {{Mono|.basex}}.
 
 
If the server is started as Servlet, all [[Options#Main Options|Main Options]] (such as the path to the database) can be configured in the {{Mono|web.xml}} file. If run as a standalone application, the settings are stored in the file {{Mono|.basex}}.
 
  
 
=Module Declarations=
 
=Module Declarations=

Revision as of 17:10, 24 March 2012

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. Note that various details of the specification may be subject to change due to the early state of the API.

Getting started

First of all, launch the BaseX as Web Application. By default, Jetty is used as web server. All HTTP services will be available on port 8984, and the RESTXQ service is accessible at http://localhost:8984/restxq/. If the server is started as servlet, all Main Options (such as the path to the database) can be configured in the web.xml file. If run as a standalone application, the settings are stored in the file .basex.

Module Declarations

A RESTXQ module needs to contain a declaration to the namespace http://exquery.org/ns/restxq. 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.

All files with extension *.xqm, placed inside the directory specified by HTTPPATH (refer to HTTP Server Configuration) will be treated as RESTXQ modules. These will be parsed for RESTXQ annotations and cached. If a module is modified, it will be parsed again at runtime.

A simple RESTXQ module is shown below, it is part of a clean installation and available at http://localhost:8984/restxq/ .

(:~ simplified module as in http/restxq.xqm :)
module namespace page = 'http://basex.org/modules/web-page';
declare namespace rest = 'http://exquery.org/ns/restxq';

declare %rest:path("hello/{$world}")
        %rest:GET
        %rest:header-param("User-Agent", "{$agent}")
        function page:hello($world as xs:string, $agent as xs:string*) {
  <response>
    <title>Hello { $world }!</title>
    <info>You requested this page with { $agent }.</info>
  </response>
};

If the URI http://localhost:8984/restxq/hello/world is accessed, the result will be kind of

<response>
	<title>Hello world!</title>
	<info>You requested this page with Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/525.13 (KHTML, like Gecko) Chrome/0.2.149.27 Safari/525.13.</info>
</response>

We added another method within that module:

declare %rest:path("form/")
        %rest:POST
        %rest:form-param("content","{$message}", "'no message delivered'")
        function page:hello-postman($message as xs:string) {
  <response>
    <title>Hello!</title>
    <info>It seems you posted a message: { $message }</info>
  </response>
};

If you posted something (e.g. using curl or the embedded formular at http://localhost:8984/restxq/ )

curl -i -X POST --data "content='Here comes the post'" http://admin:admin@localhost:8984/restxq/form

You would recieve

<response>
  <title>Hello!</title>
  <info>It seems you posted a message: 'Here comes the post'</info>
</response>

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 the values of the actual request path to the function arguments.

The following example contains a path annotation with three segments and two templates. One of the function arguments is further specified with a data type, which means that the value for $variable will be cast to an xs:integer before being bound:

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

HTTP Methods

The HTTP method annotations relate to some of the HTTP request methods (GET, HEAD, DELETE, POST, PUT). Depending on the request method of the request, a function is invoked.

Simple Method Annotations

All available simple method annotations:

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

Content Method Annotations

The variable declaration, for processing the content in a XQuery function, is optional. All available 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, 43, 44)
%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: