Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
* Quality factors in the [[#Content Negotiation|Accept header]] will be evaluated
{{Mark|Updated with Version 8.6To 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.* RESTXQ file File monitoring has been improved and can be adjusted via the new [[Options#PARSERESTXQ{{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 [[RESTXQ Module#rest:init|rest:init]] function.* Authentication was readded to RESTXQ (see [[Web Application]] for more details).
{{Mark|Updated with Version 9.0}}: The dubious status code {{Code|410}} (which indicates that a resource is permanently removed) was replaced with {{Code|460}}.
→Custom Response
* Parameters are implicitly cast to the type of the function argument
* The [[#Paths|Path Annotation]] can contain regular expressions
* <code>%input</code> annotations, support for input-specific content-type parameters
* <code>%rest:single</code> annotation to cancel running RESTXQ functions
* Quality factors in the [[#Content Negotiation|Accept header]] will be evaluated
* Support for server-side quality factors in the [[#Content Negotiation|<code>%rest:produces</code>]] annotation
<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 [[Options#RESTXQPATH{{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. 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.
==Examples==
Two following annotations can be used to restrict functions to specific content types:
* '''HTTP Content Types''': a A function will only be invoked if the HTTP {{Code|Content-Type}} header of the request matches one of the given mime content types. Example:
<pre class="brush:xquery">%rest:consumes("application/xml", "text/xml")</pre>
* '''HTTP Accept''': a A function will only be invoked if the HTTP {{Code|Accept}} header of the request matches one of the defined mime content types. Example:
<pre class="brush:xquery">%rest:produces("application/atom+xml")</pre>
By default, both mime content types are {{Code|*/*}}. Quality factors supplied by a client will also be considered in the path selection process.If a client supplies the following accept header…
<pre>
</pre>
…and if two RESTXQ functions exist with the same {{Code|path}} annotation and , one with the {{Code|produces}} annotations annotation <code>*/*</code> , and another with <code>text/html</code>, respectively, the second function with the second annotation will be called, because the quality factor for <code>text/html</code> documents is higher than the one for arbitrary other mime typeshighest.
Server-side quality factors 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: <pre class="brush:xquery">%rest:produces("text/html;qs=1")%rest:produces("*/*;qs=0.8")</pre> Note that this the annotation will ''not'' affect the content-type of the HTTP actual response. Instead, you You will need to add a supply an additional <code>[[#Output|%output:media-type]]</code> annotation.
===HTTP Methods===
==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" message="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>
};
</pre>
=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. The [[Permissions]] layer is a nice abstraction for defining permission checks.
=Functions=
;Version 9.0
* Added: Support for server-side quality factors in the [[#Content Negotiation|<code>%rest:produces</code>]] annotation* Updated: The dubious status Status code {{Code|410}} (which indicates that a resource is permanently removed) was replaced with {{Code|460}}* Removed: {{Code|restxq}} prefix
;Version 8.4
