Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
Note Please note that some BaseX provides various extensions presented in this documentation are BaseX-specific; they may be integratedin future versions to the official draft of the RESTXQ draft.specification:
The following features differ from * Multipart types are supported, including {{Code|multipart/form-data}}* A {{Code|%rest:error}} annotation can be used to catch XQuery errors* Servlet errors can be redirected to other RESTXQ pages* A [[RESTXQ Module]] provides some helper functions* Parameters are implicitly cast to the type of the RESTXQ draft:function argument
* multipart types The following features are supported, including available since {{CodeVersion|multipart/form-data8.0}}* a {{Code|%rest:error}} annotation can be used to catch XQuery errors* servlet errors can be redirected to other RESTXQ pages* a Regular expresssions in the [[RESTXQ Module#Paths|Path Annotation]] provides some helper functions* parameters Evaluation of quality factors that are implicitly cast to supplied in the type of the function argument[[#Content Negotiation|Accept header]]<br/>
no edit summary
This page presents one of the [[Web Application]] services. It describes how to use the RESTXQ API of BaseX.
RESTXQ, introduced by [http://www.adamretter.org.uk/ Adam Retter], is a new an API that facilitates the use of XQueryas a Server Side server-side processing language for the Web. RESTXQ has been inspired by Java’s
[http://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services 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.
=Usage=
===Paths===
A resource function must have a single ''Path Annotation'' with a single string as argument. The function will be called if a URL matches the path segments and templates of the argument. ''Path templates'' contain variables in curly brackets, and map the corresponding segments of the request path to the arguments of the resource function.The first slash in the path is optional;
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 <code>$variable</code> will be cast to an <code>xs:integer</code> before being bound:
declare %rest:path("/a/path/{$with}/some/{$variable}")
function page:test($with, $variable as xs:integer) { ... };
</pre>
<!-- TODO how matching works -->
Since {{Version|8.0}}, variables can be extended by regular expressions:
<pre class="brush:xquery">
(: Matches all paths with "app" as first, a number as second, and "order" as third segment :)
declare %rest:path("app/{$code=[0-9]+}/order")
function page:order($full-path) { ... };
(: Matches all other all paths starting with "app/" :)
declare %rest:path("app/{$path=.+}")
function page:others($path) { ... };
</pre>
<!-- TODO how matching works -->
<pre class="brush:xquery">%rest:produces("application/atom+xml")</pre>
By default, both mime types are {{Code|*/*}}. Since {{Version 8.0}}, quality factors supplied by a client will also be considered in the path selection process. If a client supplies the following accept header… <pre>*/*;q=0.5,text/html;q=1.0</pre> …and if two RESTXQ functions exist with the same {{Code|path}} annotation and the {{Code|produces}} annotations <code>*/*</code> and <code>text/html</code>, respectively, the function with the second annotation will be called, because the quality factor for <code>text/html</code> documents is higher than the one for arbitrary other mime types. Note that this annotation will ''not'' affect the content-type of the HTTP response. Instead, you will need to add a <code>[[#Output|%output:media-type]]</code> annotation.
===HTTP Methods===
=Changelog=
;Version 8.0
* Added: Support of regular expresssions in the [[#Paths|Path Annotation]]
* Added: Evaluation of quality factors that are supplied in the [[#Content Negotiation|Accept header]]
;Version 7.9
