Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
* Quality factors in the [[#Content Negotiation|Accept header]] will be evaluated
The To 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 fine-tuned by changing adjusted via the [[Options#PARSERESTXQ{{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|/.init}} or by calling the [[RESTXQ Module#rest:init|rest:init]] function.
The two XML elements <code>rest:forward</code> and <code>rest:redirect</code> can be used in the context of [[Web Application]]s, precisely in the context of RESTXQ. These nodes allow e.g. multiple [[XQuery Update]]s in a row by redirecting to the RESTXQ path of updating functions. Both wrap a URL to a RESTXQ path. The wrapped URL should be properly encoded via <code>fn:encode-for-uri()</code>.===Redirects===
Note that, currently, these elements are not part of RESTXQ specification{{Mark|Removed with Version 9.3:}} {{Code|rest:redirect}} element.
===restThe server can invite the client (e.g., the web browser) to make a second request to another URL by sending a 302 response:forward===
Usage: wrap the location as follows<pre class="brush:xml"><rest:forwardresponse>{ $ <http:response status="302"> <http:header name="Location" value="new-location }"/> </http:response></rest:forwardresponse></pre>
This results in The convenience function {{Function|Web|web:redirect}} can be called to create such a server-side forwarding, which as well reduces traffic among client and server. A forwarding of this kind will not change the URL seen from the client's perspectiveresponse.
As an exampleIn the XQuery context, returning<pre class="brush:xml"><rest:forward>/hello/universe</rest:forward></pre>would internally forward redirects are particularly helpful if [[XQuery Update|Updates]] are performed. An updating request may send a redirect to http://localhosta second function that generates a success message, or evaluates an updated database:8984/hello/universe
The declare %rest:path('/app/ok') function <code>[[Web Module#weblocal:ok() { 'Stored documents:redirect' ||webcount(db:redirect]]open('app'))};</codepre> can be used to create a redirect response element. Alternatively, the following element can be sent:
<pre class="brush:xml"><rest:redirect>{ $location }</rest:redirect></pre>==Forwards===
An XQuery error in a RESTXQ context delivers by default a HTTP status code 400 error back to the client. However, you can also define a custom error code by using the third argument of the error function: <pre class="brush:xquery">declare %rest:path("/teapot")function page:teapot() { fn:error(xs:QName('error'), "I'm a teapot", 418)};</pre> ==Catch HTTP Errors==
→Preliminaries
* Parameters are implicitly cast to the type of the function argument
* The [[#Paths|Path Annotation]] can contain regular expressions
* <code>%input</code> annotations, support for input-specific content-type parameters
* <code>%rest:single</code> annotation to cancel running RESTXQ functions
* Quality factors in the [[#Content Negotiation|Accept header]] will be evaluated
* Support for server-side quality factors in the [[#Content Negotiation|<code>%rest:produces</code>]] annotation
* Better support for the OPTIONS and HEAD methods
<br />
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 ''Resource Function'' is an XQuery function that has been marked up with RESTXQ annotations. When an HTTP request comes in, a resource function will be invoked that matches the constraints indicated by its annotations.
If a RESTXQ URL is requested, the [[Options#RESTXQPATH{{Option|RESTXQPATH]] }} module directory and its sub-directories will be traversed, and all [[XQuery Extensions#Suffixes|XQuery files]] will be parsed for functions with RESTXQ annotations. Sub-directories that include an {{Code|.ignore}} file will be skipped. To speed up processingIn addition, the functions of the existing XQuery modules are automatically cached in main memory. Functions that cannot be parsed will be invalidated and parsed again ignored if the timestamp of their module changes{{Option|RESTXQERRORS}} is enabled.
==Examples==
(: 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-pathcode) { ... };
(: Matches all other all paths starting with "app/" :)
</pre>
<!-- TODO how matching works -->
If multiple path candidates are found for the request, the one with more segments will be preferred.
===Content Negotiation===
Two following annotations can be used to restrict functions to specific content types:
* '''HTTP Content Types''': a A function will only be invoked if the HTTP {{Code|Content-Type}} header of the request matches one of the given mime content types. Example:
<pre class="brush:xquery">%rest:consumes("application/xml", "text/xml")</pre>
* '''HTTP Accept''': a A function will only be invoked if the HTTP {{Code|Accept}} header of the request matches one of the defined mime content types. Example:
<pre class="brush:xquery">%rest:produces("application/atom+xml")</pre>
By default, both mime content types are {{Code|*/*}}. Quality factors supplied by a client will also be considered in the path selection process.If a client supplies the following accept header…
<pre>
</pre>
…and if two RESTXQ functions exist with the same {{Code|path}} annotation and , one with the {{Code|produces}} annotations annotation <code>*/*</code> , and another with <code>text/html</code>, respectively, the second function with the second annotation will be called, because the quality factor for <code>text/html</code> documents is higher than highest. Server-side quality factors are supported as well: If multiple function candidates are left over after the above steps, the <code>qs</code> parameter will be considered. The function with the one for arbitrary other mime typeshighest quality factor will be favored: <pre class="brush:xquery">%rest:produces("text/html;qs=1")%rest:produces("*/*;qs=0.8")</pre>
Note that this the annotation will ''not'' affect the content-type of the HTTP actual response. Instead, you You will need to add a supply an additional <code>[[#Output|%output:media-type]]</code> annotation.
===HTTP Methods===
====Custom Methods====
Custom HTTP methods can be specified with the {{Code|%rest:method}} annotation. An optional body variable can be supplied as second argument:
<pre class="brush:xquery">
declare %rest:path("binary-size") %rest:method("RETRIEVESIZE", "{$body}") function page:retrievepatch( $body as xs:base64Binary) { "RETRIEVE was specified as Request method: " || request :method.(), " Size of body: " || bin:length($body)};
</pre>
{{Mark|Updated with Version 9.3:}}
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==
===Input options===
Conversion options for [[Options#JSONPARSER{{Option|JSON]]}}, [[Options#CSVPARSER{{Option|CSV]] }} and [[Options#HTMLPARSER{{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 class="brush:xquery">
In many RESTXQ search scenarios, input from browser forms is processed and search results are returned. User experience can generally be made more interactive if an updated search request is triggered with each key click. However, this may lead to many expensive parallel 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 be executed for the same client. If the same function will be called for the second time, the already running query will be stopped, and the HTTP error code {{Code|410460}} (Gone) will be returned instead:
<pre class="brush:xquery">
(: If fast enough, returns the result. Otherwise, if called again, raises 410 460 :)
declare
%rest:path("/search")
By specifying a string along with the annotation, functions can be bundled together, and one request can be canceled by calling another one.
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>410460</code>, and the second one will return <xml>stopped</xml>.
<pre class="brush:xquery">
==Custom Response==
Custom responses can be built from within 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 more optional child nodes that will be serialized as usual. A function that reacts yields a response on an unknown resource may look as follows:
<pre class="brush:xquery">
declare %output:method("text") %rest:path("") function page:error404() {
<rest:response>
<http:response status="404" message="I was not found.">
<http:header name="Content-Language" value="en"/>
<http:header name="Content-Type" value="text/htmlplain; charset=utf-8"/>
</http:response>
</rest:response>, "The requested resource is not available."
};
</pre>
==Forwards and Redirects==
<pre class==="brush:xquery">declare %updating %rest:path('/app/init') function local:create() { db:create('app', <root/>, 'root.xml'), db:output(web:redirect===('/app/ok'))};
A server-side redirect is called forwarding. It is an abbreviation forreduces traffic among client and server, and the forwarding will not change the URL seen from the client’s perspective:
<pre class="brush:xml">
<rest:responseforward> <http:response status="302"> <http:header name="location" value="{ $new-location }"/> </http:response></rest:responseforward>
</pre>
The client decides whether to follow this redirection. Browsers usually will, tools like [http://curl.haxx.se/ curl] won’t unless fragment can also be created with the convenience function {{CodeFunction|-LWeb|web:forward}} is specified.
==Output==
=Error Handling=
==Raise Errors== {{Mark|Updated with Version 9.3}}: If an error is raised during the evaluation of a RESTXQ function, an HTTP response with the status code 400 is generated. The response body contains the full error message and stack trace. With the {{Function|Web|web:error}} function, you can abort query evaluation and enforce a premature HTTP response with the supplied status code and response body text: <pre class="brush:xquery">declare %rest:path("/teapot")function page:teapot() { web:error(418, "I'm a pretty teapot")};</pre> The XQuery error code and the stack trace will be suppressed in the body of the HTTP response. ==Catch XQuery Errors==
XQuery runtime errors can be processed via ''error annotations''.
</pre>
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>
=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=
=Changelog=
;Version 9.3
* Updated: [[#Custom Methods|Custom Methods]]: Better support for the OPTIONS and HEAD methods.
* Updated: [[#Catch XQuery Errors|XQuery Errors]]: Suppress stack trace and error code in the HTTP response.
* Removed: {{Code|rest:redirect}} element ({{Function|Web|web:redirect}} can be used instead)
;Version 9.2
* Updated: Ignore XQuery modules that cannot be parsed
;Version 9.0
* Added: Support for server-side quality factors in the [[#Content Negotiation|<code>%rest:produces</code>]] annotation
* Updated: Status code {{Code|410}} was replaced with {{Code|460}}
* Removed: {{Code|restxq}} prefix
;Version 8.4
;Version 7.9
* Updated: [[#Catch XQuery Errors|XQuery Errors]], extended error annotations
* Added: {{Code|%rest:method}}
