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>>
{{Mark|Updated with Version 9.3:}}
{{Mark|Removed with Version 9.3:}} {{Code|rest:redirect}} element.
==Raise Errors==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,
{{Mark|Updated with Version 9* 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.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 traceinformation can still be looked up in the database logs.
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"
This page presents one of the [[Web Application]] services. It describes how to use the RESTXQ API of BaseX.
RESTXQ, introduced by [http://www.adamretter.org.uk/ Adam Retter], is an API that facilitates the use of XQueryas a server-side processing language for the Web. RESTXQ It has been inspired by Java’sthe Java [httphttps://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services JAX-RS API]: it defines It provides a pre-defined set ofXQuery 3.0 annotations for mapping HTTP requests to XQuery functions, which in turn generate and returnHTTP responses.
Please note that BaseX provides various extensions to the original draft of the specification:
==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…
====Default Methods====
The HTTP method annotations are equivalent to all [httphttps://en.wikipedia.org/wiki/HTTP#Request_methods HTTP request methods] except TRACE and CONNECT. Zero or more methods may be used on a function; if none is specified, the function will be invoked for each method.
The following function will be called if GET or POST is used as request method:
};
</syntaxhighlight>
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.
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==
===Redirects===
The server can invite the client (e.g., the web browser) to make a second request to another URL by sending a 302 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=
==Raise Errors== 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:
<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">
Examples:
* Sample code combining XQuery and JavaScript: [httphttps://www.balisage.net/Proceedings/vol17/author-pkg/Galtman01/BalisageVol17-Galtman01.html Materials] and [httphttps://www.balisage.net/Proceedings/vol17/html/Galtman01/BalisageVol17-Galtman01.html paper] from Amanda Galtman, Balisage 2016.
* [[DBA]]: The Database Administration interface, bundled with the full distributions of BaseX.
=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: [[#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.
;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}}
;Version 8.4
* Added: <code>%rest:single</code> annotation
;Version 8.1
* Added: support for input-specific content-type parameters
* Added: <code>%input</code> annotations
;Version 8.0
* Added: Support for regular expresssions in the [[#Paths|Path Annotation]]
* Added: Evaluation of quality factors that are supplied in the [[#Content Negotiation|Accept header]]
;Version 7.9
* Updated: [[#Catch XQuery Errors|XQuery Errors]], extended error annotations
* Added: {{Code|%rest:method}}
;Version 7.7
* Added: [[#Error Handling|Error Handling]], [[#File Uploads|File Uploads]], [[#Multipart Types|Multipart Types]]
* Updated: RESTXQ function may now also be specified in main modules (suffix: {{Code|*.xq}}).
* 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/>}}
