1. Accessing Form Parameters with %rest:form-param

The annotation %rest:form-param is provided for accessing parameters from an HTML form submitted where the HTTP Content-Type header matches the application/x-www-form-urlencoded Media Type.

declare
  %rest:path("/search")
  %rest:form-param('query', '{$q}')
function perform-search($q as xs:string) {
  <results>{
    cts:search(fn:doc(), cts:parse($q))[1 to 10]
  }</results>
};

A client could call this function by using the following HTML Form

<form action="/search" method="POST">
  <input type="text" name="query" />
  <input type="submit" />
</form>

In this case the query Form Parameter is mapped to the Function parameter $q.

Unfortunately, due to a limitation in MarkLogic, only one %rest:form-param annotation can be used per function. To accept more Form Parameters, you can use numbered Form Param Annotations, such as %rest:form-param-1, %rest:form-param-2, %rest:form-param-3 etc. Consider the following example

declare
  %rest:path("/search")
  %rest:form-param-1('query', '{$q}')
  %rest:form-param-2('from', '{$from}')
  %rest:form-param-3('to', '{$to}')
function perform-search(
  $q as xs:string,
  $from as xs:integer,
  $to as xs:integer) {
  <results>{
    cts:search(fn:doc(), cts:parse($q))[$from to $to]
  }</results>
};

A client could call this function by using the following HTML form

<form action="/search" method="POST">
  <input type="text" name="query" />
  <input type="hidden" name="from" value="1" />
  <input type="hidden" name="to" value="10" />
  <input type="submit" />
</form>

2. Automatic Type Conversion

XQRS will automatically convert the Form Parameter into the required parameter type at runtime for you, providing the parameter type inherits from xs:anyAtomicType

Parameters received from Form Parameters can be optional and as such the occurrence indicator on those parameters can be '?'.

declare
  %rest:path("/my-little-service")
  %rest:form-param('optional-param', '{$opt}')
function optional($opt as xs:date?) {
  if(fn:exists($opt)) then
    'got date ' || $opt
  else
    'optional-param not given.'
};

If automatic type conversion is not possible, for instance the parameter expects a date but the value given for that parameter can not be cast to a date then an exception is thrown explaining this.

3. Default Values

You can give Form Parameters default values, in case the client has not given a value for that parameter. Consider the following example

declare
  %rest:path("/document-in-collection")
  %rest:form-param-1('collection', '{$col}', 'my-default')
  %rest:form-param-2('id', '{$id}', '1234')
function optional($col as xs:string, $id as xs:integer) {
  fn:collection($col)/doc[@id = $id]
};

4. Receiving a Sequence of values

It's possible to receive a list of different values for a Form Parameter, for instance a HTML Form could look like the following

<form action="/my-service" method="POST">
  <input type="hidden" name="a" value="1" />
  <input type="hidden" name="a" value="2" />
  <input type="hidden" name="a" value="3" />
  <input type="hidden" name="a" value="4" />
  <input type="submit" />
</form>

A request like that could be handled by the following Function

declare
%rest:path("/my-service")
%rest:form-param('a', '{$a}')
function list($a as xs:integer*) {
  'found ' || count($a) || ' values'
};

You can even use a list of values as default parameters if you so wished

declare
  %rest:path("/my-service")
  %rest:form-param('a', '{$a}', 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
function list($a as xs:integer+) {
  'found ' || count($a) || ' values'
};