Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
no edit summary
HTTP responses.
Note that various details of the specification may be subject to change due to the early state of the API. Next, with {{Version 7.7}}, the RESTXQ prefix has been changed from {{Code|restxq}} to {{Code|rest}}.
=Usage=
module namespace page = 'http://basex.org/examples/web-page';
declare %restxqrest:path("hello/{$world}") %restxqrest:GET %restxqrest:header-param("User-Agent", "{$agent}")
function page:hello($world as xs:string, $agent as xs:string*) {
<response>
<pre class="brush:xquery">
declare %restxqrest:path("form/") %restxqrest:POST %restxqrest:form-param("content","{$message}", "'no message delivered'")
function page:hello-postman($message as xs:string) {
<response>
<pre class="brush:xquery">
declare %restxqrest:path("/a/path/{$with}/some/{$variable}")
function page:test($with, $variable as xs:integer) { ... };
</pre>
<pre class="brush:xquery">
declare %restxqrest:GET %restxqrest:POST %restxqrest:path("")
function page:root() { <html/> };
</pre>
<pre class="brush:xquery">
declare %restxqrest:PUT("{$data}") %restxqrest:path("")
function page:put($data) { "Data: " || $data };
</pre>
* '''HTTP Content Types''': a function will only be invoked if the HTTP {{Code|Content-Type}} header of the request matches one of the given mime types. Example:
<pre class="brush:xquery">%restxqrest:consumes("application/xml", "text/xml")</pre>
* '''HTTP Accept''': a function will only be invoked if the HTTP {{Code|Accept}} header of the request matches one of the defined mime types. Example:
<pre class="brush:xquery">%restxqrest:produces("application/atom+xml")</pre>
By default, both mime types are {{Code|*/*}}. Note that this annotation will ''not'' affect the content-type of the HTTP response. Instead, you will need to add a <code>[[#Output|%output:media-type]]</code> annotation.
<pre class="brush:xquery">
%restxqrest:query-param("parameter", "{$value}", "default")%restxqrest:query-param("answer", "{$answer}", 42, 43, 44)%restxqrest:query-param("search", "{$search-param}")
</pre>
<pre class="brush:xquery">
%restxqrest:form-param("parameter", "{$value}", "default")
</pre>
<pre class="brush:xquery">
%restxqrest:header-param("User-Agent","{$user-agent}")%restxqrest:header-param("Referer","{$referer}", "none")
</pre>
<pre class="brush:xquery">
%restxqrest:cookie-param("username","{$user}")%restxqrest:cookie-param("authentication","{$auth}", "no_auth")
</pre>
<pre class="brush:xquery">
declare %output:media-type("text/plain") %restxqrest:path("")
function page:kiss() { 'keep it simple, stupid' };
</pre>
<pre class="brush:xquery">
declare
%restxqrest:path("")
%output:method("xhtml")
%output:omit-xml-declaration("no")
import module namespace request = "http://exquery.org/ns/request";
declare %restxqrest:path("/host-name") function test:host() {
'Remote host name: ' || request:remote-hostname()
};
Since RESTXQ runs on a fully equipped Web-server, one can change all and specify more HTTP header informations that are returned to the client. By default, a successful request is answered with HTTP status code "200 OK" followed by the given content, an erroneous request (due to errors in a script) with "404 Not Found" followed by the error message.
The first behavior can be changed by returning an <code>restxqrest:response</code> element, following the [http://expath.org/spec/http-client EXPath HTTP Client Module] specification. E.g. one may return to the client
<pre class="brush:xml">
<restxqrest:response>
<http:response status="418" message="I'm a teapot">
<http:header name="Content-Language" value="en"/>
<http:header name="Content-Type" value="text/html; charset=utf-8"/>
</http:response>
</restxqrest:response>
<html>
<body>My Message</body>
Compare [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes List of HTTP status codes] to see what status code fits.
It is mandatory to first place <code>restxqrest:response</code> followed by the content (of any kind) if any. In case of an updating function, use [[Database_Module#db:output|db:output()]] to return the element and the content.
=Forward and Redirect=
The two XML elements <code>restxqrest:forward</code> and <code>restxqrest:redirect</code> can be used in the context of [[Web Application]]s, precisely in the context of RESTXQ. These nodes allow e.g. multiple [[XQuery Update]]s in a row by redirecting to the RESTXQ path of updating functions. Both wrap a URL to a RESTXQ path. The wrapped URL should be properly encoded via <code>fn:encode-for-uri()</code>.
Note that, currently, these elements are not part of RESTXQ specification.
==restxqrest:forward==
Usage: wrap the location as follows
<pre class="brush:xml"><restxqrest:forward>{ $location }</restxqrest:forward></pre>
This results in a server-side forwarding, which as well reduces traffic among client and server. A forwarding of this kind will not change the URL seen from the client's perspective.
As an example, returning
<pre class="brush:xml">
<restxqrest:forward>/restxq/hello/universe</restxqrest:forward>
</pre>
would internally forward to http://localhost:8984/restxq/hello/universe
==restxqrest:redirect==
<pre class="brush:xml"><restxqrest:redirect>{ $location }</restxqrest:redirect></pre>
…is basically an abbreviation for…
<pre class="brush:xml">
<restxqrest:response>
<http:response status="302" message="Temporary Redirect">
<http:header name="location" value="{ $location }"/>
</http:response>
</restxqrest:response>
</pre>
;Version 7.5
* Updated: the default RESTXQ prefix has been changed from {{Code|restxq}} to {{Code|rest}}.
;Version 7.5
* Added: new XML elements {{Code|<restxqrest:redirect/>}} and {{Code|<restxqrest:forward/>}}
[[Category:HTTP]]
[[Category:Developer]]
