Main Page » XQuery » Functions » Web Functions

Web Functions

This module provides convenience functions for building web applications with RESTXQ.

Conventions

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

Functions

Removed: web:forward: server-side forwarding was dropped.

web:content-type

Signature
web:content-type(
  $path  as xs:string
) as xs:string
SummaryReturns a content type for a path by analyzing the file suffix. application/octet-stream is returned if no mapping exists for the suffix.

Note that the returned value may change over time.

Examples
web:content-type('sample.mp3')
Result: 'audio/mpeg'

web:create-url

Signature
web:create-url(
  $href        as xs:string,
  $parameters  as map(*)?  := {},
  $anchor      as xs:string?  := ''
) as xs:string
SummaryCreates 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', { 'q': 'dog' })
Result: 'http://find.me?q=dog'
web:create-url('search', { 'year': (2000,2001), 'title': () })
Result: `search?year=2000&year=2001`

web:encode-url

Signature
web:encode-url(
  $value  as xs:string
) as xs:string
SummaryEncodes the specified string $value 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")
Result: 'this+is+a+test%21.html'

web:decode-url

Signature
web:decode-url(
  $value  as xs:string
) as xs:string
SummaryDecodes the specified URL $value 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")
Result: '日本語'

web:redirect

Updated: Status parameter added.

Signature
web:redirect(
  $url         as xs:string,
  $parameters  as map(*)?  := {},
  $anchor      as xs:string?  := '',
  $status      as xs:integer?  := 302
) as element(rest:response)
SummaryCreates 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 for web:create-url.
Examples
web:redirect('/a/b')
…is interpreted as redirection directive if RESTXQ is used. The result:
<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

updated: message attribute removed (deprecated Servlet API feature).

Signature
web:response-header(
  $output    as map(*)?  := (),
  $headers   as map(*)?  := (),
  $response  as map(*)?  := ()
) as element(rest:response)
SummaryCreates a RESTXQ response header.

Serialization parameters and header values can be supplied via the $output and $headers arguments, and a status attribute can be attached to the HTTP response element with the $response argument.

Examples
web:response-header(
  { 'media-type': 'application/octet-stream' },
  { 'Cache-Control': 'max-age=3600,public' },
  { 'status': 200 }
)
Returns a media-type for binary data, a caching directive, and the OK status.
declare %rest:path('media/{$file}') function local:get($file) {
  let $path := 'path/to/' || $file
  return (
    web:response-header({ 'media-type': web:content-type($path) }),
    file:read-binary($path)
  )
};
Returns the contents of a file to the client with correct media type.
web:response-header()
The result:
<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>

web:error

Updated: $message can now be an arbitrary item, and serialization parameters can be supplied via the new $options argument.

Signature
web:error(
  $status   as xs:integer,
  $message  as item()*,
  $options  as map(*)?  := {}
) as none
SummaryRaises an error that is turned into an HTTP response with the supplied $status code and $message as response body:
  • The error is raised with the QName rest:status{$status} (e.g. rest:status404), so that it can be caught by a RESTXQ error function.
  • $message is bound to the error value ($err:value) and may be an arbitrary item, such as a map or an array. If the error is not caught, the value is serialized and returned as response body.
  • Serialization parameters can be supplied via $options (see Serialization). The default method is text; the resulting media type is used as Content-Type of the response.

See RESTXQ: Raise Errors to learn how the function is helpful in web applications.

Examples
web:error(404, "The requested resource cannot be found.")
Returns a 404 response with a plain-text body.
web:error(400, { 'error': 'Invalid id' }, { 'method': 'json' })
Returns a 400 response with a JSON body (media type application/json).

Changelog

Version 13
  • Updated: web:error: $message can be an arbitrary item; serialization $options added.
  • Updated: web:response-header: message attribute removed (deprecated Servlet API feature).
  • Updated: web:redirect: Status parameter added.
  • Removed: web:forward: server-side forwarding was dropped.
Version 9.3Version 9.2Version 9.0
  • Updated: web:response-header: third argument added; default parameters removed.
  • Updated: error codes updated; errors now use the module namespace
Version 8.4Version 8.2Version 8.1
  • Added: New module added.
⚡Generated with XQuery
 
Login | Changelog | TOC | Imprint
Web Functions