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 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>. Note that, currently, these elements are not part of RESTXQ specification. ===rest:forwardRedirects===
Usage{{Mark|Removed with Version 9.3: wrap the location as follows<pre class="brush:xml"><}} {{Code|rest:forward>{ $location redirect}}</rest:forward></pre>element.
This results in a The server-side forwarding, which as well reduces traffic among can invite the client and server(e.g. A forwarding of this kind will not change , the web browser) to make a second request to another URL seen from the client's perspective.by sending a 302 response:
As an example, returning
would internally forward to http://localhost:8984/hello/universe
===restThe convenience function {{Function|Web|web:redirect===}} can be called to create such a response.
The function <code>In the XQuery context, redirects are particularly helpful if [[Web Module#web:redirectXQuery Update|web:redirectUpdates]]</code> can be used are performed. An updating request may send a redirect to create a redirect response element. Alternativelysecond function that generates a success message, the following element can be sentor evaluates an updated database:
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. {{MarkOption|Updated with Version 8.6:RESTXQERRORS}}is enabled.
To speed up processing, the functions of the existing XQuery modules are automatically cached in main memory:* RESTXQ file Functions will be invalidated and parsed again if the timestamp of their module changes.* File monitoring has been improved and can be adjusted via the new [[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.* Authentication was readded to RESTXQ (see [[Web Application]] for more details).
==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 one for arbitrary other mime types<code>qs</code> parameter will be considered.The function with the highest 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">
==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:xml">
<rest:forwardresponse> <http:response status="302"> <http:header name="Location" value="new-location"/hello> </universehttp:response></rest:forwardresponse>
</pre>
<pre class="brush:xmlxquery"><declare %updating %rest:redirect>path('/app/init') function local:create() { $location } db:create('app', <root/rest>, 'root.xml'), db:output(web:redirect><('/app/pre>ok'))};
declare %rest:path('/app/ok') function local:ok() { 'Stored documents: ' || count(db:open('app'))};</pre> ===Forwards=== 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}}
