Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
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. {{Mark|Updated with Version 9.3}}: If the error code has the RESTXQ namespace, the stack trace and the error code will be suppressed in the client output: <pre class="brush:xquery">declare %rest:path("/teapot")function page:teapot() { fn:error(xs:QName('rest:error'), "I'm a teapot", 418)};</pre> ==Catch HTTP Errors==
→Preliminaries
* 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 {{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. With {{Version|9.2}}In addition, XQuery modules that cannot be parsed will be ignored as wellif {{Option|RESTXQERRORS}} is enabled.
To speed up processing, the functions of the existing XQuery modules are automatically cached in main memory:
};
</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==
==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]):
;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
;Version 7.9
* Updated: [[#Catch XQuery Errors|XQuery Errors]], extended error annotations
* Added: {{Code|%rest:method}}
