Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
With {{Version|9.0}}, support for serverServer-side quality factors was added. 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 highest quality factor will be favored:
{{Mark|Updated with Version 9.0:}} The old status code {{Code|410}} (which indicates to the client that a resource is permanently removed) was replaced with {{Code|460}}.
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==
→Forwards and Redirects
* <code>%rest:single</code> annotation to cancel running RESTXQ functions
* Quality factors in the [[#Content Negotiation|Accept header]] will be evaluated
* {{Version|9.0}}: 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}}, XQuery modules that cannot be parsed will be ignored as well.
To speed up processing, the functions of the existing XQuery modules are automatically cached in main memory:
(: 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===
…and if two RESTXQ functions exist with the same {{Code|path}} annotation, one with the {{Code|produces}} annotation <code>*/*</code>, and another with <code>text/html</code>, the second function will be called, because the quality factor for <code>text/html</code> documents is highest.
<pre class="brush:xquery">
====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">
==Query Execution==
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.
==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" reason="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]):
=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. With {{Version|9.0}} of BaseX, a The [[Permissions]] layer was introduced to facilitate 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
;Version 7.9
* Updated: [[#Catch XQuery Errors|XQuery Errors]], extended error annotations
* Added: {{Code|%rest:method}}
