Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
<<response>> <<title>>Hello World!<</title>><</response>>
<<response type='form'>> <<message>>{ $message }<</message>> <<user-agent>>{ $agent }<</user-agent>> <</response>>
Multiple types can either be specified by a single or by multiple annotations. If no annotations are specified, {{Code|*/*}} is the default type.
{{Mark|Updated with Version 9.3:}}
{{Mark|Removed with Version 9.3:}} {{Code|rest:redirect}} element.
{{Mark|Updated with Version 9.3}}:
→Examples
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:
<syntaxhighlight lang="xml">
</syntaxhighlight>
$agent as xs:string*
) as element(response) {
};
</syntaxhighlight>
===Content Negotiation===
Functions can be restricted to specific Media Types:. The default type is {{Code|*/*}}. Multiple types can either be specified by a single or by multiple annotations.
====Consuming Data====
<syntaxhighlight lang="xquery">
declare
%rest:POST("{$body}")
%rest:path("/xml")
%rest:consumes("application/xml")
%rest:consumes("text/xml")
function page:xml($body) { <xml/> $body };
</syntaxhighlight>
function page:xml() { <xml/> };
</syntaxhighlight>
Note that the annotations will ''not'' affect the type of the actual response: You will need to supply an additional <code>[[#Output|%output:media-type]]</code> annotation or (if a single function may produce results of different types) generate an apt [[#Custom_Response|Custom Response]].
====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.
===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:
==Raise Errors==
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.
=Functions=
The [[Request Module]] contains functions for accessing data related to the current HTTP request. Two 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]]). The [[RESTXQ Module]] provides functions for requesting RESTXQ base URIs and generating a [httphttps://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:
* [http://www.adamretter.org.uk/papers/restful-xquery_january-2012.pdf RESTful XQuery, Standardised XQuery 3.0 Annotations for REST]. Paper, XMLPrague, 2012
* [http://www.adamretter.org.uk/presentations/restxq_mugl_20120308.pdf RESTXQ]. Slides, MarkLogic User Group London, 2012
* [httphttps://files.basex.org/publications/xmlprague/2013/Develop-RESTXQ-WebApps-with-BaseX.pdf Web Application Development]. Slides from XMLPrague 2013
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.
;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}}).
;Version 7.5
* Added: new XML elements {{Code|<rest:redirect/>}} and {{Code|<rest:forward/>}}
