Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
m
<<response>> <<title>>Hello World!<</title>><</response>>
<<response type='form'>> <<message>>{ $message }<</message>> <<user-agent>>{ $agent }<</user-agent>> <</response>>
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 and report errors back to the supplied status code and response body textclient:
The XQuery In contrast to the standard <code>fn:error </code> function, a status code can be supplied, and the response body will only contain the specified error message and no stack trace will be suppressed in the body of the HTTP response.
Text replacement - "8984" to "8080"
==Preliminaries==
The RESTXQ service is accessible via {{Code|http://localhost:89848080/}}.
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 subdirectories will be traversed, and all [[XQuery Extensions#Suffixes|XQuery files]] will be parsed for functions with RESTXQ annotations. Sub-directories Subdirectories that include an {{Code|.ignore}} file will be skipped. In addition, XQuery modules that cannot be parsed will be ignored if {{Option|RESTXQERRORS}} is enabled.
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 adjusted via the {{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 [[{{Function|RESTXQ Module#rest:init|rest:init]] }} function.
==Examples==
<title>Hello { $who }!</title>
</response>
};</syntaxhighlight>
If the URI http://localhost:89848080/hello/World is accessed, the result will be:
<syntaxhighlight lang="xml">
</syntaxhighlight>
$agent as xs:string*
) as element(response) {
};
</syntaxhighlight>
If you post something (e.g. using curl or the embedded form at http://localhost:89848080/)...
<syntaxhighlight lang="shell">
curl -i -X POST --data "message='CONTENT'" http://localhost:89848080/form
</syntaxhighlight>
A client can supply quality factors to influence the server-side function selection process. If a client sends the following HTTP header with quality factors…
<syntaxhighlightpre>
Accept: */*;q=0.5,text/html;q=1.0
</syntaxhighlightpre>
…and if two RESTXQ functions exist for the addressed path with two different annotations for producing data…
by specifying additional content-type parameters:
{| class="wikitable" width="100%"
|- valign="top"
! Content-Type
! Parameters (<code>;name=value</code>)
! Type of resulting XQuery item
|-valign="top"
| {{Code|text/xml}}, {{Code|application/xml}}
|
| {{Code|document-node()}}
|-valign="top"
| {{Code|text/*}}
|
| {{Code|xs:string}}
|-valign="top"
| {{Code|application/json}}
| [[JSON Module#Options|JSON Options]]
| {{Code|document-node()}} or {{Code|map(*)}}
|-valign="top"
| {{Code|text/html}}
| [[HTML Module#Options|HTML Options]]
| {{Code|document-node()}}
|-valign="top"
| {{Code|text/comma-separated-values}}
| [[CSV Module#Options|CSV Options]]
| {{Code|document-node()}} or {{Code|map(*)}}
|-valign="top"
| ''others''
|
| {{Code|xs:base64Binary}}
|-valign="top"
| {{Code|multipart/*}}
|
===HTML Form Fields===
Form parameters are specified the same way as [[#Query Parameters|query parameters]]. Their values are the result of HTML forms submitted with the content type <code>application/x-www-form-urlencoded</code>.:
<syntaxhighlight lang="xquery">
%rest:form-param("parametercity", "{$valuecity}", "no-city-specified")</syntaxhighlight> The values are the result of HTML forms submitted with the (default) content type <code>application/x-www-form-urlencoded</code>: <syntaxhighlight lang=")xml"><form action="/process" method="POST" enctype="application/x-www-form-urlencoded"> <input type="text" name="city"/> <input type="submit"/></form>
</syntaxhighlight>
<syntaxhighlight lang="xml">
<form action="/upload" method="POST" enctype="multipart/form-data">
<input type="file" name="files" multiple="multiple"/>
<input type="submit"/>
</form>
==Query Execution==
In many RESTXQ web search scenarios, user input from browser forms is processed and search results are returned. User experience Such operations can generally be made more interactive if an updated by sending a new search request is triggered to the server with each key click. However, this may lead to many expensive parallel server-side 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 run at the same time and for the same client. If the same function will be called for the second time, the already running a currently executed query will be stopped, and the HTTP error code {{Code|460}} will be returned instead:
<syntaxhighlight lang="xquery">
function page:search($term as xs:string) {
<ul>{
for $result in db:openget('large-db')//*[text() = $term]
return <li>{ $result }</li>
}</ul>
</syntaxhighlight>
By specifying adding a string along value to with the annotation, functions can be bundled together, and one request a running query can be canceled by calling another onethat has the same annotation value. 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>460</code>, and the second one will return <xml>stopped</xml>.
<syntaxhighlight lang="xquery">
The following things should be noted:
* If a query will be canceled, there will be no undesirable side-effects. For example, it won’t be possible to kill abort a query if it is currenly currently updating the database or perfoming performing any other I/O operations. As a result, the termination of a running query can take some more time as expected.
* The currently executed function is bound to the current session. This way, a client will not be able to cancel requests from other clients. As a result, functions can only be stopped if there was at least one previous successful response, in which initial session data was returned to the client.
By default, a successful request is answered with the HTTP status code {{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”).
A {{Code|Server-Timing}} HTTP header is attached to each response. It indicates how much time was spent for parsing, compiling, evaluating and serializing the query. The last value will not necessarily reflect the full time for serializing the result, as the header is generated before the result is sent to the client. Server-side serialization can be enforced by annotating a function with the <code>[[#Query Execution|%rest:single]]</code> annotation.
==Custom Response==
declare %rest:path('/app/ok') function local:ok() {
'Stored documents: ' || count(db:openget('app'))
};
</syntaxhighlight>
function page:cities() {
element cities {
db:openget('factbook')//city/name
}
};
=Error Handling=
If an error is raised when RESTXQ code is parsed, compiled or evaluated, an HTTP response with the status code 500 is generated.
By default, all server-side errors will be passed on to the client. This is particularly helpful during the development process. In a productive environment, however, it is advisable not to expose errors to the client. This can be realized via the {{Option|RESTXQERRORS}} option. If disabled,
* XQuery modules that cannot be parsed will be ignored and
* full error messages and stack traces will be suppressed and not included in the HTTP response.
The full error information can still be looked up in the database logs.
==Raise Errors==
<syntaxhighlight lang="xquery">
</syntaxhighlight>
==Catch XQuery Errors==
XQuery runtime errors can be processed via ''error annotations''.Error annotations have one or more arguments, which represent the error codes to be caught.The codes equal the names of the XQuery 3.0 [[XQuery 3.0#Try.2FCatch|try/catch]] construct:
{| class="wikitable"
! Syntax
! Example
|-valign="top"
| 1
| <code>prefix:name</code><br/><code>Q{uri}name</code>
| <code>err:FORG0001</code><br/><code><nowiki>Q{http://www.w3.org/2005/xqt-errors}FORG0001</nowiki></code>
|-valign="top"
| 2
| <code>prefix:*</code><br/><code>Q{uri}*</code>
| <code>err:*</code><br/><code><nowiki>Q{http://www.w3.org/2005/xqt-errors}*</nowiki></code>
|-valign="top"
| 3
| <code>*:name</code>
| <code>*:FORG0001</code>
|-valign="top"
| 4
| <code>*</code>
</syntaxhighlight>
The target location may be another RESTXQ function. The [[{{Function|Request Module#request:attribute|request:attribute]] }} function can be used to request details on the caught error:
<syntaxhighlight lang="xquery">
=Changelog=
;Version 9.6
* Updated: [[#Response|Response]]: {{Code|Server-Timing}} HTTP header.
;Version 9.5
* Updated: [[#Raise Errors|Raise Errors]]: Status code {{Code|400}} changed to {{Code|500}}, omit stack trace.
;Version 9.3
* Updated: the RESTXQ prefix has been changed from {{Code|restxq}} to {{Code|rest}}.
* Updated: parameters are implicitly cast to the type of the function argument
* Updated: the RESTXQ root url has been changed to {{Code|http://localhost:89848080/}}
;Version 7.5
* Added: new XML elements {{Code|<rest:redirect/>}} and {{Code|<rest:forward/>}}
