Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
The [[Request Module]] contains functions for accessing data related to the current HTTP request. Two additional 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]]). With {{Mark|Introduced with Version|7.7:}}, a [[RESTXQ Module]] was added that provides functions for requesting RESTXQ base URIs and generating a [http://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 XQuery errors can be processed via ''error annotations''. Errors can be unexpected, or deliberately generated in a query, as the following example returns the current host nameshows:
import module namespace request = "http://exquery.org/ns/request";
</pre>
=Response= By default, a successful request is answered with the [httpdeclare %rest://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP status 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”'err:user'). Custom responses can be built from within XQuery by returning an <code>restfunction test:response</code>, 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. E.g. one may return to the client <pre class="brush:xml"><rest:response>user() { <http:response status="404" message="I was not found.">'User is unknown' <http:header name="Content-Language" value="en"/> <http:header name="Content-Type" value="text/html}; charset=utf-8"/> </http:response></rest:response>
==Error Handling==
{{Mark|Introduced with Version 7.7:}}
no edit summary
</pre>
=Functions=Error Handling==
<pre class="brush:xquery">
module namespace test = 'http://basex.org/examples/test';
declare %rest:path("'/host-name"check/{$user}') function test:hostcheck($user) { if($user = ('jack', 'lisa')) then 'Everything ok'Remote host name else error(xs: QName(' || requesterr:remote-hostname(user'))
};
</pre>
Errors that occur outside RESTXQ can be handled by adding {{Code|error-page}} elements 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]):
</html>
};
</pre>
=Functions=
The [[Request Module]] contains functions for accessing data related to the current HTTP request. Two additional 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]]). With {{Version|7.7}}, a [[RESTXQ Module]] was added that provides functions for requesting RESTXQ base URIs and generating a [http://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 class="brush:xquery">
module namespace test = 'http://basex.org/examples/test';
import module namespace request = "http://exquery.org/ns/request";
declare %rest:path("/host-name") function test:host() {
'Remote host name: ' || request:remote-hostname()
};
</pre>
=Response=
By default, a successful request is answered with the [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP status 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”).
Custom responses can be built from within XQuery by returning an <code>rest:response</code>, 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. E.g. one may return to the client
<pre class="brush:xml">
<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/html; charset=utf-8"/>
</http:response>
</rest:response>
</pre>
