Web Module

This XQuery Module provides convenience functions for building web applications with RESTXQ.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/web namespace, which is statically bound to the web prefix.

Functions

web:content-type

Signature	web:content-type( $path as xs:string ) as xs:string
Summary	Returns the content type of a path by analyzing its file suffix. application/octet-stream is returned if the file suffix is unknown.
Examples	web:content-type("sample.mp3") returns audio/mpeg

web:create-url

Signature	web:create-url( $href as xs:string, $parameters as map(*), $anchor as xs:string := () ) as xs:string
Summary	Creates a new URL from the specified $href string, query string $parameters and an optional $anchor reference. The keys and values of the map entries will be converted to strings, URL-encoded (see web:encode-url), and appended to the URL as query parameters. If a map entry has more than a single item, all of them will be appended as single parameters.
Examples	web:create-url('http://find.me', map { 'q': 'dog' }) returns http://find.me?q=dog web:create-url('search', map { 'year': (2000,2001), 'title':() }) returns search?year=2000&year=2001

web:encode-url

Signature	web:encode-url( $string as xs:string ) as xs:string
Summary	Encodes a string to a URL. Spaces are rewritten to +; *, -, . and _ are adopted; and all other non-ASCII characters and special characters are percent-encoded.
Examples	web:encode-url("this is a test!.html") returns this+is+a+test%21.html.

web:decode-url

Signature	web:decode-url( $string as xs:string ) as xs:string
Summary	Decodes a URL to the original string. Percent-encoded characters are decoded to their UTF8 codepoints, and + characters are rewritten to spaces.
Examples	web:decode-url("%E6%97%A5%E6%9C%AC%E8%AA%9E") returns 日本語.
Errors	invalid: the string contains invalid XML characters.

web:forward

Signature	web:forward( $path as xs:string, $parameters as map(*) := () ) as element(rest:forward)
Summary	Creates a server-side RESTXQ forward request to the specified $path: The client will not get notified of this forwarding. Supplied query parameters will be attached to parameters of the current request. The $parameter argument is processed as described in web:create-url.
Examples	The function call web:forward('/a/b') creates the following result (which will be interpreted as forwarding if RESTXQ is used): <rest:forward>/a/b</rest:forward>

web:redirect

Signature	web:redirect( $url as xs:string, $parameters as map(*) := (), $anchor as xs:string := () ) as element(rest:response)
Summary	Creates a RESTXQ redirection to the specified $url. The returned response will only work if no other items are returned by the RESTXQ function. The $parameters and $anchor arguments are processed as described in (see web:create-url).
Examples	The query web:redirect('/a/b') returns the following result (which will be interpreted as redirection if RESTXQ is used): <rest:response xmlns:rest="http://exquery.org/ns/restxq"> <http:response xmlns:http="http://expath.org/ns/http-client" status="302"> <http:header name="location" value="/a/b"/> </http:response> </rest:response>

web:response-header

Signature	web:response-header( $output as map(*)? := (), $headers as map(*)? := (), $atts as map(*)? := () ) as element(rest:response)
Summary	Creates a RESTXQ response header. Serialization parameters and header values can be supplied via the $output and $headers arguments, and status and message attributes can be attached to the HTTP response element with the $atts argument. media-type: application/octet-stream Header options can be supplied via the $headers argument. Empty string values can be specified to invalidate default values. By default, the following header options will be returned: Cache-Control: max-age=3600,public
Examples	The function call web:response-header() returns: <rest:response xmlns:rest="http://exquery.org/ns/restxq"> <http:response xmlns:http="http://expath.org/ns/http-client"/> <output:serialization-parameters xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization"/> </rest:response> The following expression returns a media-type for binary data, a caching directive, and the OK status: web:response-header( map { 'media-type': 'application/octet-stream' }, map { 'Cache-Control': 'max-age=3600,public' }, map { 'status': 200, 'message': 'OK' } ) The following RESTXQ function returns the contents of a file to the client with correct media type: declare %rest:path('media/{$file}') function local:get($file) { let $path := 'path/to/' || $file return ( web:response-header(map { 'media-type': web:content-type($path) }), file:read-binary($path) ) };

web:error

Signature	web:error( $status as xs:integer, $message as xs:string ) as none
Summary	Raises an error with the QName rest:error, the specified $message and the specified $status as error value. Calls to this function are equivalent to fn:error(xs:QName('rest:error'), $message, $status). See RESTXQ: Raise Errors to learn how the function is helpful in web applications.
Examples	web:error(404, "The requested resource cannot be found.")
Errors	status: The supplied status code is invalid.

Errors

Code	Description
invalid	A string contains invalid XML characters.
status	The supplied status code is invalid.

Changelog

Version 9.3

• Added: web:error, web:forward

Version 9.2

• Updated: web:create-url, web:redirect: third argument added.

Version 9.0

• Updated: web:response-header: third argument added; default parameters removed.
• Updated: error codes updated; errors now use the module namespace

Version 8.4

• Updated: web:response-header: serialization method raw was removed (now obsolete).

Version 8.2

• Added: web:encode-url, web:decode-url.

The module was introduced with Version 8.1.