Web Module

From BaseX Documentation
Revision as of 11:54, 8 July 2020 by CG (talk | contribs)
Jump to navigation Jump to search

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

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:forward

Signatures web:forward($path as xs:string) as element(rest:forward)
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.
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

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>

web:response-header

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

Signatures 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
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.