Changes

This page is part presents one of the [[Developer SectionWeb 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 It has been inspired by Java’sthe Java [httphttps://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services JAX-RS API]: it defines It provides a pre-defined set ofXQuery 3.0 annotations for mapping HTTP requests to XQuery functions, which in turn generate and returnHTTP responses. As of {{Version|7.2}}, RESTXQ is supported by BaseX.

<!-* 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 [[CGRESTXQ Module] I guess we need another general page on ] provides some helper functions* Parameters are implicitly cast to the HTTP Server and type of the Servlet that summarizes all this information... -->function argumentFirst of all, launch the * The [[Startup#BaseX HTTP ServerPaths|BaseX HTTP ServerPath Annotation]], which will itself start an instance of the [http:can contain regular expressions* <code>%input<//jetty.codehaus.org/jetty/ Jetty WebServer]code> annotations, which listens to the port support for input-specific content-type parameters* <code>8984%rest:single</code> by default (check out annotation to cancel running RESTXQ functions* Quality factors in the additional [[Startup Options#BaseX HTTP ServerContent Negotiation|commandAccept header]] will be evaluated* Support for server-line optionsside quality factors in the [[#Content Negotiation|<code>%rest:produces</code>]]).annotation* Better support for the OPTIONS and HEAD methods<br/>

=Module Declarations=Preliminaries==

A The RESTXQ module must contain a declaration to the namespace service is accessible via {{MonoCode|http://exquery.org/ns/restlocalhost:8080/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.

All RESTXQ [[XQuery 3.0#Annotations|annotations]] are assigned to the <code><nowiki>http://exquery.org/ns/restxq</nowiki></code> namespace, which is statically bound to the {{Code|rest}} prefix. A simple ''Resource Function'' is an XQuery function that has been marked up with RESTXQ module is shown below:annotations. When an HTTP request comes in, a resource function will be invoked that matches the constraints indicated by its annotations.

<pre class="brush:xquery">(:~ A simple If a RESTXQ URL is requested, the {{Option|RESTXQPATH}} module directory and its subdirectories will be traversed, and all [[XQuery Extensions#Suffixes|XQuery files]] will be parsed for functions with REST-RESTXQ annotations :)module namespace hw = 'http://basex.org/modules/restxq-demo';Subdirectories that include an {{Code|.ignore}} file will be skipped.

declare namespace rest = 'httpTo speed up processing, the functions of the existing XQuery modules are automatically cached in main memory:* Functions will be invalidated and parsed again if the timestamp of their module changes.* File monitoring can be adjusted via the {{Option|PARSERESTXQ}} option. In productive environments with a high load, it may be recommendable to change the timeout, or completely disable monitoring.* If files are replaced while the web server is running, the RESTXQ module cache should be explicitly invalidated by calling the static root path {{Code|//exquery.org/ns/init}} or by calling the {{Function|RESTXQ|rest/annotation';:init}} function.

%rest:path("/form") %rest:POST %rest:form-param("message","{$pathmessage}", "(no message)") %outputrest:mediaheader-typeparam("application/xmlUser-Agent", "{$agent}")function hwpage:demohello-postman( $path message as xs:string, $agent as xs:string*) as element(response) { &lt;xml&gt;<response type='form'> <message>{ $message }</message> Hello World! You accessed the path <user-agent>{ $path agent }.</user-agent> &lt;</xml&gt;response>};</pre> If you post something (e.g. using curl or the embedded form at http://localhost:8080/)... <pre lang="shell">curl -i -X POST --data "message='CONTENT'" http://localhost:8080/form</pre>

If ...you will receive something similar to the URI {{Mono|httpfollowing result: <pre lang="shell">HTTP/1.1 200 OKContent-Type: application/localhostxml; charset=UTF-8Content-Length: 107Server:8984Jetty(8.1.11.v20130520)</restxq/demo-module}} is accessed, the result will bepre>

<pre classlang="brush:xml">&lt;xml&gt;<response type="form"> <message>'CONTENT'</message> Hello World! You accessed the path demo<user-moduleagent>curl/7.31.0</user-agent>&lt;</xml&gt;response></pre>

=AnnotationsRequest=

This section lists all shows how annotations provided by RESTXQ. <code>rest</code> is are used as namespace prefixto handle and process HTTP requests.

A resource function must have a single ''Path Annotation''with a single string as argument. It The function will be called if a URL matches the path segments and templates specified as of the argument. ''Path templates'' contain variables in curly brackets, and map the corresponding segments of the request path values to the arguments of the resource function. The following example represents a first slash in the path annotation with three segments and two templates: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: <pre classlang="brush:'xquery"'>

functionpage:test($with, $variableas xs:integer) { ... };</pre><!-- TODO how matching works --> Variables can be enhanced by regular expressions: <pre lang='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($code) { ... }; (: Matches all other all paths starting with "app/" :)declare %rest:path("app/{$path=.+}") function page:others($path) { ... };

* Simple Method Annotations====Default Methods==== The HTTP method annotations are equivalent to all [https://en.wikipedia.org/wiki/HTTP#Request_methods HTTP request methods] except TRACE and CONNECT. Zero or more methods may be used on a function; if none is specified, the function will be invoked for each method. The following function will be called if GET or POST is used as request method: <pre classlang='xquery'>declare %rest:GET %rest:POST %rest:path("/post") function page:post() { "This was a GET or POST request"brush};</pre> The POST and PUT annotations may optionally take a string literal in order to map the HTTP request body to a [[#Parameters|function argument]]. Once again, the target variable must be embraced by curly brackets: <pre lang='xquery'>declare %rest:PUT("{$body}") %rest:path("/put") function page:put($body) { "Request body: "|| $body };</pre> ====Custom Methods==== Custom HTTP methods can be specified with the {{Code|%rest:GETmethod}} annotation. An optional body variable can be supplied as second argument: <pre lang='xquery'>declare %rest:HEADpath("binary-size") %rest:DELETEmethod("SIZE", "{$body}")function page:patch( $body as xs:base64Binary) { "Request method: " || request:method(), "Size of body: " || bin:length($body)};

* If an OPTIONS request is received, and if no function is defined, an automatic response will be generated, which includes an <code>Allow</code> header with all supported methods. If a HEAD request is received, and if no function is defined, the corresponding GET function will be processed, but the response body will be discarded. ==Content Types== The body of a POST or PUT request will be converted to an XQuery item. Conversion can becontrolled by specifying a content type. It can be further influencedby specifying additional content-type parameters: {| class="wikitable"|- valign="top"! Content Method Annotations-Type! Parameters (<code>;name=value<pre class/code>)! Type of resulting XQuery item|- valign="top"| {{Code|text/xml}}, {{Code|application/xml}}|| {{Code|document-node()}}|- valign="top"| {{Code|text/*}}|| {{Code|xs:string}}|- valign="top"| {{Code|application/json}}| [[JSON Module#Options|JSON Options]]| {{Code|document-node()}} or {{Code|map(*)}}|- valign="top"| {{Code|text/html}}| [[HTML Module#Options|HTML Options]]| {{Code|document-node()}}|- valign="top"| {{Code|text/comma-separated-values}}| [[CSV Module#Options|CSV Options]]| {{Code|document-node()}} or {{Code|map(*)}}|- valign="brushtop"| ''others''|| {{Code|xs:base64Binary}}|- valign="top"| {{Code|multipart/*}}|| sequence (see next paragraph)|} For example, if <code>application/json;lax=yes</code> is specified as content type, the input will be transformed to JSON, and the lax QName conversion rules will be applied, as described in the [[JSON Module]]. ===Input options=== Conversion options for {{Option|JSON}}, {{Option|CSV}} and {{Option|HTML}} can also be specified via annotations with the <code>input</code> prefix. The following function interprets the input as text with the CP1252 encoding and treats the first line as header: <pre lang='xquery"'>declare %rest:POSTpath("/store.csv") %rest:POST("{$post-bodycsv}") %restinput:PUTcsv("header=true,encoding=CP1252")%restfunction page:PUTstore-csv("{$putcsv as document-body}node()) { "Number of rows: "|| count($csv/csv/record)};

===Content Multipart Types===

* '''HTTP Content Types''': One or more media-types may be specified The single parts of a multipart message are represented as stringsa sequence, e.g.:<br/><pre class="brush:xquery">%rest:consumes("application/xml", "text/xml")</pre>* '''HTTP Accept''': One or more media-types may be specified and each part is converted to an XQuery item as strings, edescribed in the last paragraph.g.:<br/><pre class="brush:xquery">%rest:produces("application/atom+xml")</pre>

These default A function that is capable of handling multipart types is identical to other RESTXQ functions: <codepre lang='xquery'>*declare %rest:path("/multipart") %rest:POST("{$data}") %rest:consumes("multipart/mixed") (: optional :)function page:multipart($data as item()*) { "Number of items: " || count($data)};</codepre> if no media-type annotations are given.

Parameters are optional The following annotations that can be used to bind additional request values to function arguments:. Values will implicitly be cast to the type of the argument.

===Query StringsParameters===

The value of the <em>''first parameter</em>'', if found in the [http://en.wikipedia.org/wiki/Query_string Query String[Request_Module#Conventions|query component]], will be assigned to the variable specified as <em>''second parameter</em>''. OptionallyIf no value is specified in the HTTP request, a <em>third all additional parameters will be bound to the variable (if no additional parameter</em> may is given, an empty sequence will be specified as defaultbound):

<pre classlang='xquery'>declare %rest:path("brush:xquery/params">) %rest:query-param("parameterid", "{$valueid}", "default") %rest:query-param("answeradd", "{$answeradd}", 42, 43, 44)%restfunction page:query-paramparams($id as xs:string?, $add as xs:integer+) { <result id="search{ $id }", sum="{sum($search-paramadd) }")/>};

Form parameters are specified the same way as [[#Query StringsParameters|query stringsparameters]]. Their values are extracted from GET or POST requests.:

<pre classlang='xquery'>%rest:form-param("city", "{$city}", "no-city-specified")</pre> The values are the result of HTML forms submitted with the (default) content type <code>application/x-www-form-urlencoded</code>: <pre lang="xml"><form action="/process" method="POST" enctype="application/x-www-form-urlencoded"> <input type="text" name="city"/> <input type="submit"/></form></pre> ====File Uploads==== Files can be uploaded to the server by using the content type {{Code|multipart/form-data}} (the HTML5 {{Code|multiple}} attribute enables the upload of multiple files): <pre lang="xml"><form action="/upload" method="POST" enctype="multipart/form-data"> <input type="file" name="files" multiple="multiple"/> <input type="brushsubmit"/></form></pre> The file contents are placed in a [[Map Module|map]], with the filename serving as key. The following example shows how uploaded files can be stored in a temporary directory: <pre lang='xquery'>declare %rest:POST %rest:path("/upload">) %rest:form-param("parameterfiles", "{$valuefiles}")function page:upload($files) { for $name in map:keys($files) let $content := $files($name) let $path := file:temp-dir() || $name return ( file:write-binary($path, $content), <file name="default{ $name }" size="{ file:size($path) }"/> )};

Header parameters are specified the same way as [[#Query StringsParameters|query stringsparameters]]:

<pre classlang="brush:'xquery"'>%rest:header-param("User-Agent","{$user-agent}")%rest:header-param("Referer","{$referer}", "none")

Cookie parameters are specified the same way as [[#Query StringsParameters|query stringsparameters]]:

<pre classlang="brush:'xquery"'>%rest:cookie-param("username","{$user}")%rest:cookie-param("authentication","{$auth}", "no_auth")</pre> ==Query Execution== In many web search scenarios, user input from browser forms is processed and search results are returned. Such operations can be made more interactive by sending a new search request to the server with each key click. However, this may lead to many parallel server-side requests, from which only the result of the last request will be relevant for the client. With the <code>%rest:single</code> annotation, it can be enforced that only one instance of a function will run at the same time and for the same client. If the same function will be called for the second time, a currently executed query will be stopped, and the HTTP error code {{Code|460}} will be returned instead: <pre lang='xquery'>(: If fast enough, returns the result. Otherwise, if called again, raises 460 :)declare %rest:path("/search") %rest:query-param("term", "{$term}") %rest:singlefunction page:search($term as xs:string) { <ul>{ for $result in db:get('large-db')//*[text() = $term] return <li>{ $result }</li> }</ul>};</pre> By adding a string value to with the annotation, functions can be bundled together, and a running query can be canceled by calling another one that has the same annotation value. This is shown by another example, in which the first function can be interrupted by the second one. If you call both functions in separate browser tabs, you will note that the first tab will return <code>460</code>, and the second one will return <xml>stopped</xml>. <pre lang='xquery'>declare %rest:path("/compute") %rest:single("EXPENSIVE")function local:compute() { (1 to 100000000000000)[. = 0]}; declare %rest:path("/stop") %rest:single("EXPENSIVE")function local:stop() { <xml>stopped</xml>};</pre> The following things should be noted: * If a query will be canceled, there will be no undesirable side effects. For example, it won’t be possible to abort a query if it is currently updating the database or performing any other I/O operations. As a result, the termination of a running query can take some more time as expected.* The currently executed function is bound to the current session. This way, a client will not be able to cancel requests from other clients. As a result, functions can only be stopped if there was at least one previous successful response, in which initial session data was returned to the client. =Response= By default, a successful request is answered with the HTTP status code {{Code|200}} (OK) and is followed by the given content. An erroneous request leads to an error code and an optional error message (e.g. {{Code|404}} for “resource not found”). A {{Code|Server-Timing}} HTTP header is attached to each response. It indicates how much time was spent for parsing, compiling, evaluating and serializing the query. The last value will not necessarily reflect the full time for serializing the result, as the header is generated before the result is sent to the client. Server-side serialization can be enforced by annotating a function with the <code>[[#Query Execution|%rest:single]]</code> annotation. ==Custom Response== Custom responses can be generated in XQuery by returning an <code>rest:response</code> element, an <code>http:response</code> child node that matches the syntax of the [http://expath.org/spec/http-client EXPath HTTP Client Module] specification, and optional child nodes that will be serialized as usual. A function that yields a response on an unknown resource may look as follows: <pre lang='xquery'>declare %output:method("text") %rest:path("") function page:error404() { <rest:response> <http:response status="404"> <http:header name="Content-Language" value="en"/> <http:header name="Content-Type" value="text/plain; charset=utf-8"/> </http:response> </rest:response>, "The requested resource is not available."};</pre> For the time being, it is not possible to create multipart responses. ==Forwards and Redirects== ===Redirects=== The server can invite the client (e.g., the web browser) to make a second request to another URL by sending a 302 response: <pre lang="xml"><rest:response> <http:response status="302"> <http:header name="Location" value="new-location"/> </http:response></rest:response></pre> The convenience function {{Function|Web|web:redirect}} can be called to create such a response. In the XQuery context, redirects are particularly helpful if [[XQuery Update|Updates]] are performed. An updating request may send a redirect to a second function that generates a success message, or evaluates an updated database: <pre lang='xquery'>declare %updating %rest:path('/app/init') function local:create() { db:create('app', <root/>, 'root.xml'), db:output(web:redirect('/app/ok'))}; declare %rest:path('/app/ok') function local:ok() { 'Stored documents: ' || count(db:get('app'))};</pre> ===Forwards=== A server-side redirect is called forwarding. It reduces traffic among client and server, and the forwarding will not change the URL seen from the client’s perspective: <pre lang="xml"><rest:forward>new-location</rest:forward></pre> The response can also be created with the convenience function {{Function|Web|web:forward}}. With {{Announce|Version 11}}, a log entry with the status code {{Code|204}} will be output before the forwarding takes place. ==Output== The content-type of a response can be influenced by the user via [[Serialization|Serialization Parameters]]. The steps are described in the [[REST#Content Type|REST]] chapter. In RESTXQ, serialization parameters can be specified in the query prolog, via annotations, or within the REST response element: ===Query Prolog=== In main modules, serialization parameters may be specified in the query prolog. These parameters will then apply to all functions in a module. In the following example, the content type of the response is overwritten with the {{Code|media-type}} parameter: <pre lang='xquery'>declare option output:media-type 'text/plain'; declare %rest:path("version1") function page:version1() { 'Keep it simple, stupid'};</pre> ===Annotations=== Global serialization parameters can be overwritten via <code>%output</code> annotations. The following example serializes XML nodes as JSON, using the [[JSON Module|JsonML]] format: <pre lang='xquery'>declare %rest:path("cities") %output:method("json") %output:json("format=jsonml")function page:cities() { element cities { db:get('factbook')//city/name }};</pre> The next function, when called, generates XHTML headers, and {{Code|text/html}} will be set as content type: <pre lang='xquery'>declare %rest:path("done") %output:method("xhtml") %output:omit-xml-declaration("no") %output:doctype-public("-//W3C//DTD XHTML 1.0 Transitional//EN") %output:doctype-system("http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd")function page:html() { <html xmlns="http://www.w3.org/1999/xhtml"> <body>done</body> </html>};</pre> ===Response Element=== Serialization parameters can also be specified in a REST reponse element in a query. Serialization parameters will be overwritten: <pre lang='xquery'>declare %rest:path("version3") function page:version3() { <rest:response> <output:serialization-parameters> <output:media-type value='text/plain'/> </output:serialization-parameters> </rest:response>, 'Not that simple anymore'};</pre> =Error Handling= If an error is raised when RESTXQ code is parsed, compiled or evaluated, an HTTP response with the status code 500 is generated. By default, all server-side errors will be passed on to the client. This is particularly helpful during the development process. In a productive environment, however, it is advisable not to expose errors to the client. This can be realized via the {{Option|RESTXQERRORS}} option. If disabled, * XQuery modules that cannot be parsed will be ignored and* full error messages and stack traces will be suppressed and not included in the HTTP response. The full error information can still be looked up in the database logs. ==Raise Errors== With {{Function|Web|web:error}}, you can abort query evaluation, enforce a premature HTTP response and report errors back to the client: <pre lang='xquery'>declare %rest:path("/teapot")function page:teapot() { web:error(418, "I'm a pretty teapot")};</pre> In contrast to the standard <code>fn:error</code> function, a status code can be supplied, and the response body will only contain the specified error message and no stack trace. ==Catch XQuery Errors== XQuery runtime errors can be processed via ''error annotations''. Error annotations have one or more arguments, which represent the error codes to be caught. The codes equal the names of the [[XQuery 3.0#Try.2FCatch|try/catch]] construct: {| class="wikitable"|- valign="top"! Precedence! Syntax! Example|- valign="top"| 1| <code>prefix:name</code><br/><code>Q{uri}name</code>| <code>err:FORG0001</code><br/><code><nowiki>Q{http://www.w3.org/2005/xqt-errors}FORG0001</nowiki></code>|- valign="top"| 2| <code>prefix:*</code><br/><code>Q{uri}*</code>| <code>err:*</code><br/><code><nowiki>Q{http://www.w3.org/2005/xqt-errors}*</nowiki></code>|- valign="top"| 3| <code>*:name</code>| <code>*:FORG0001</code>|- valign="top"| 4| <code>*</code>| <code>*</code>|} All error codes that are specified for a function must have the same precedence.The following rules apply when catching errors: * Codes with a higher precedence (smaller number) will be given preference.* A global RESTXQ error will be raised if two functions with conflicting codes are found. Similar to try/catch, the pre-defined variables ({{Code|code}}, {{Code|description}}, {{Code|value}}, {{Code|module}}, {{Code|line-number}}, {{Code|column-number}}, {{Code|additional}}) can be bound to variables via ''error parameter annotations'', which are specified the same way as [[#Query Parameters|query parameters]]. Errors may occur unexpectedly. However, they can also be triggered by a query, as demonstrated by the following example: <pre lang='xquery'>declare %rest:path("/check/{$user}")function page:check($user) { if($user = ('jack', 'lisa')) then 'User exists' else fn:error(xs:QName('err:user'), $user)}; declare %rest:error("err:user") %rest:error-param("description", "{$user}")function page:user-error($user) { 'User "' || $user || '" is unknown'};</pre> ==Catch HTTP Errors== Errors that occur outside RESTXQ can be caught by adding {{Code|error-page}} elements with an error code and a target location to the {{Code|web.xml}} configuration file (find more details in the [http://www.eclipse.org/jetty/documentation/current/custom-error-pages.html Jetty Documentation]): <pre lang="xml"><error-page> <error-code>404</error-code> <location>/error404</location></error-page></pre> The target location may be another RESTXQ function. The {{Function|Request|request:attribute}} function can be used to request details on the caught error: <pre lang='xquery'>declare %rest:path("/error404") function page:error404() { "URL: " || request:attribute("javax.servlet.error.request_uri") || ", " || "Error message: " || request:attribute("javax.servlet.error.message")};</pre> =User Authentication= If you want to provide restricted access to parts of a web applications, you will need to check permissions before returning a response to the client. The [[Permissions]] layer is a nice abstraction for defining permission checks. =Functions= The [[Request Module]] contains functions for accessing data related to the current HTTP request. Two modules exist for setting and retrieving server-side session data of the current user ([[Session Module]]) and all users known to the HTTP server ([[Sessions Module]]). The [[RESTXQ Module]] provides functions for requesting RESTXQ base URIs and generating a [https://www.w3.org/Submission/wadl/ WADL description] of all services. Please note that the namespaces of all of these modules must be explicitly specified via module imports in the query prolog. The following example returns the current host name: <pre lang='xquery'>import module namespace request = "http://exquery.org/ns/request"; declare %rest:path("/host-name") function page:host() { 'Remote host name: ' || request:remote-hostname()};

RESTXQ has been proposed by [http://www.adamretter.org.uk/ Adam Retter].More information on all specifics can be found in the following two documentsDocumentation:

[[Category;Version 7.5* Added:Server]][[Categorynew XML elements {{Code|<rest:redirect/>}} and {{Code|<rest:Developer]]forward/>}}