Difference between revisions of "RESTXQ"
Line 54: | Line 54: | ||
=RESTful Annotations= | =RESTful Annotations= | ||
− | + | This section lists all available annotations. <code>rest</code> is used as namespace prefix. | |
+ | ==Constraints== | ||
+ | |||
+ | Constraining annotations restrict the access to functions if specific properties are fulfilled: | ||
+ | |||
+ | ===Path Annotation=== | ||
− | |||
<code>%rest:path("/a/path/{$with}/some/{$variable}")</code> | <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. | 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. | ||
Line 64: | Line 68: | ||
A function is allowed to have <strong>at least one</strong> path annotation. | A function is allowed to have <strong>at least one</strong> path annotation. | ||
− | + | ===HTTP Method Annotations=== | |
− | ==HTTP Method Annotations | ||
* Simple Method Annotations | * Simple Method Annotations | ||
Line 82: | Line 85: | ||
<!-- TODO add some descripton --> | <!-- TODO add some descripton --> | ||
− | ==Media Type Annotations | + | ===Media Type Annotations=== |
+ | |||
* HTTP Content Type<br/><code>%rest:consumes()</code> one or more media-types as string. e.g.<code>%rest:consumes("application/xml", "text/xml") | * HTTP Content Type<br/><code>%rest:consumes()</code> one or more media-types as string. e.g.<code>%rest:consumes("application/xml", "text/xml") | ||
* HTTP Accept<br/><code>%rest:produces()</code> one media-type as string. e.g. <code>%rest:produces("application/atom+xml")</code> | * HTTP Accept<br/><code>%rest:produces()</code> one media-type as string. e.g. <code>%rest:produces("application/atom+xml")</code> | ||
Line 88: | Line 92: | ||
These default to <code>*/*</code>, if no media-type annotations are given. | These default to <code>*/*</code>, if no media-type annotations are given. | ||
− | ==Query String Annotations | + | ==Parameters== |
+ | |||
+ | Parameters are optional annotations that can be used to bind additional values to function arguments: | ||
+ | |||
+ | ===Query String Annotations=== | ||
<code>%rest:query-param()</code> | <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. | 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. | ||
Line 98: | Line 106: | ||
* <code>%rest:query-param("search", "{$search-param}")</code> | * <code>%rest:query-param("search", "{$search-param}")</code> | ||
+ | ===HTML Form field Annotations=== | ||
− | |||
<code>%rest:form-param()</code> | <code>%rest:form-param()</code> | ||
− | same usage as [[#Query String Annotations | + | same usage as [[#Query String Annotations]], but extracted from POST or GET. |
<!-- TODO remark on file submission --> | <!-- TODO remark on file submission --> | ||
− | ==HTTP Header Annotations | + | ===HTTP Header Annotations=== |
+ | |||
<code>%rest:header-param()</code> | <code>%rest:header-param()</code> | ||
− | same usage as [[#Query String Annotations | + | same usage as [[#Query String Annotations]], but extracted from HTTP Header. |
Examples | Examples | ||
Line 113: | Line 122: | ||
* <code>%rest:header-param("Referer","{$referer}", "none")</code> | * <code>%rest:header-param("Referer","{$referer}", "none")</code> | ||
− | ==Cookie Annotations | + | ===Cookie Annotations=== |
+ | |||
<code>%rest:cookie-param()</code> | <code>%rest:cookie-param()</code> | ||
− | same usage as [[#Query String Annotations | + | same usage as [[#Query String Annotations]], but extracted from Cookie. |
Examples | Examples |
Revision as of 23:26, 16 March 2012
This page is part of the Developer Section. It describes how to use RESTXQ of BaseX.
RESTXQ is a new standard API with RESTful XQuery Annotations, presented by Adam Retter at this year's XML Prague Conference and MarkLogic User Group. It further simplifies web application development in XQuery.
As of Version 7.2, RESTfulXQ 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>
RESTful Annotations
This section lists all available annotations. rest
is used as namespace prefix.
Constraints
Constraining annotations restrict the access to functions if specific properties are fulfilled:
Path Annotation
%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
- 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
- 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 String Annotations
%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 field Annotations
%rest:form-param()
same usage as #Query String Annotations, but extracted from POST or GET.
HTTP Header Annotations
%rest:header-param()
same usage as #Query String Annotations, but extracted from HTTP Header.
Examples
%rest:header-param("User-Agent","{$user-agent}")
%rest:header-param("Referer","{$referer}", "none")
Cookie Annotations
%rest:cookie-param()
same usage as #Query String Annotations, but extracted from Cookie.
Examples
%rest:cookie-param("username","{$user}")
%rest:cookie-param("authentication","{$auth}", "no_auth")