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
Signatures
|
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
Template:Mark Third argument added.
Signatures
|
web:create-url($url as xs:string, $parameters as map(*)) as xs:string
web:create-url($url as xs:string, $parameters as map(*), $anchor as xs:string) as xs:string
|
Summary
|
Creates a new URL from the specified $url 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
Signatures
|
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
Signatures
|
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:redirect
Template:Mark Third argument added.
Signatures
|
web:redirect($url as xs:string) as element(rest:response)
web:redirect($url as xs:string, $parameters as map(*)) as element(rest:response)
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>
- The first RESTXQ function creates an initial database, and redirects to a second function that will access this database:
declare %updating %rest:path('/app/init') function local:init() {
db:create('app', <root/>, 'root.xml'),
db:output(web:redirect('/app/main'))
};
declare %rest:path('/app/main') function local:update() {
'Stored documents: ' || count(db:open('app'))
};
|
Signatures
|
web:response-header() as element(rest:response)
web:response-header($output as map(*)?) as element(rest:response)
web:response-header($output as map(*)?, $headers as map(*)?) as element(rest:response)
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
Template:Mark
Signatures
|
web:error($status as xs:integer, $message as xs:string) as none
|
Summary
|
$status}} as error value. See Raise XQuery Errors for further details).
|
Examples
|
web:eror(404, "The requested resource cannot be found.")
|
Errors
Code
|
Description
|
invalid
|
A string contains invalid XML characters.
|
status
|
The supplied status code is invalid.
|
Changelog
- Version 9.3
- Version 9.2
- 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
- Version 8.2
The module was introduced with Version 8.1.