REST

In order to use Zorba's REST functionality, the module "http://www.zorba-xquery.com/zorba/rest-functions" has to be included at the beginning of a query.

For example

  import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions";

Currently, Zorba provides function to setup HTTP GET, PUT and POST requests. We'll add additional functions for HEAD and DELETE with a later release. Moreover, all of the functions will be declared nondeterministic (as in the upcoming XQuery 1.1. specification) and sequential (as in the upcoming XQuery Scripting specification).

REST Functions

The following section defines the various REST XQuery functions (and their parameters) provided by Zorba.

GET Functions

 declare nondeterministic sequential function zorba-rest:get( url as xs:string)                         as element(zorba-rest:result);
 declare nondeterministic sequential function zorba-rest:get( url as xs:string,
                                                              payload as element(zorba-rest:payload))   as element(zorba-rest:result);
 declare nondeterministic sequential function zorba-rest:get( url as xs:string,
                                                              payload as element(zorba-rest:payload),
                                                              headers as element(zorba-rest:headers)*)  as element(zorba-rest:result);

GetTidy Functions

In order to use the functions that require Tidy you have to:

• install Tidy either from binaries or source code.
  
• rebuild Zorba with ZORBA_WITH_TIDY set to ON.
  

 declare nondeterministic sequential function zorba-rest:getTidy( url as xs:string,
                                                                  $tidyOptions as xs:string)                as element(zorba-rest:result);
 declare nondeterministic sequential function zorba-rest:getTidy( url as xs:string,
                                                                  $tidyOptions as xs:string,
                                                                  payload as element(zorba-rest:payload))   as element(zorba-rest:result);
 declare nondeterministic sequential function zorba-rest:getTidy( url as xs:string,
                                                                  $tidyOptions as xs:string
                                                                  payload as element(zorba-rest:payload),
                                                                  headers as element(zorba-rest:headers)*)  as element(zorba-rest:result);

A complete set of options that can be set for the Tidy call can be found at HTML Tidy Configuration Options

By default Zorba sets these values for the following options:

• char-encoding=utf8
  
• newline=LF
  
• tidy-mark=true
  
• quote-nbsp=no
  

These options can be overwritten by passing different $tidyOptions.
For instance if $tidyOptions is '"newline=CRLF","doctype=omit","force-output","bare=yes"' that would mean that:

• newline will be set to CRLF (see newline)
  
• doctype will be set to omit (see doctype)
  
• force-output will be set to true (see force-output)
  
• bare will be set to true (see bare)
  

Note: you can set a boolean parameter to true by either of the following methods:

• passing only the option name (like force-output in the above example)
  
• passing the option name and the value (like bare in the above example)
  

POST Functions

 declare nondeterministic sequential function zorba-rest:post(url as xs:string)                         as element(zorba-rest:result);
 declare nondeterministic sequential function zorba-rest:post(url as xs:string,
                                                              payload as element(zorba-rest:payload))   as element(zorba-rest:result);
 declare nondeterministic sequential function zorba-rest:post(url as xs:string,
                                                              payload as element(zorba-rest:payload),
                                                              headers as element(zorba-rest:headers)*)  as element(zorba-rest:result);

POST Functions

 declare nondeterministic sequential function zorba-rest:put( url as xs:string)                         as element(zorba-rest:result);
 declare nondeterministic sequential function zorba-rest:put( url as xs:string,
                                                              payload as element(zorba-rest:payload))   as element(zorba-rest:result);
 declare nondeterministic sequential function zorba-rest:put( url as xs:string,
                                                              payload as element(zorba-rest:payload),
                                                              headers as element(zorba-rest:headers)*)  as element(zorba-rest:result);

Parameter Descriptions

URL

The URL as an xs:string. This can be either a HTTP or a HTTPS URL optionally containing additional parameters.

Payload

For the GET function, the payload should have the form:

 <zorba-rest:payload>
   <zorba-rest:part name="parameter name">parameter value</zorba-rest:part>
     ...
 </zorba-rest:payload>

Accepted parameter values are text nodes. The payload will be assembled as key-value pairs and appended to the URL address.

The POST function accepts any of the following three forms for the payload:

 <zorba-rest:payload filename="filename" content-type="type"/>

 <zorba-rest:payload content-type="content-type">data</zorba-rest:payload>

 <zorba-rest:payload content-type="multipart/form-data">
   <zorba-rest:part name="part name">part value</zorba-rest:part>
   <zorba-rest:part name="part name" filename="file" content-type="type"/>
     ...
 </zorba-rest:payload>

In the first two forms the content-type attribute is optional and if missing, a default value is used. In the first form the given file will be posted, with the default content type of "application/octet-stream". In the second form data may either be a string or an XML part, with the default content type of "text/plain" and "text/xml", respectively. The third form can be used to post HTML form data and the part values may be either text nodes or XML parts.

Headers

Custom headers to be sent with the HTTP request.

 <zorba-rest:headers>
   <zorba-rest:header name="header name">header value</zorba-rest:header>
   ...
 <zorba-rest:headers>

Result

Contains the reply of the HTTP request.

  <zorba-rest:result>
    <zorba-rest:status_code>code</zorba-rest:status_code>
    <zorba-rest:headers>
      <zorba-rest:header name="header name">header value</zorba:rest:header>
      ...
    </zorba-rest:headers>
    <zorba-rest:payload>
      Payload contents 
      ...
    </zorba-rest:payload>
  </zorba-rest:result>

The headers part contains the headers sent by the servers, e.g. content-type, content-length, etc. The payload will be: an XML part when the content type is xml or xhtml, a text node for all content-types that begin with "text/" (except "text/xml"), and a Base64 encoded value in all the other cases.

Errors

An error will be generated for any reply that has a status code different from 200. The payload, however, will be returned too, if available.

REST Examples

REST GET Examples

Example 1

(: Simple GET example :)
import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions";

zorba-rest:get("http://www.google.com/")

Example 2

(: Invoke Google search for the "zorba xquery" term :)

import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions";

zorba-rest:get("http://www.google.com/search",
               <payload>
                <part name="q">zorba xquery</part>
               </payload>)

Example 3

(: Invoke zorba-rest:get and pass a value for the Referer header :)

import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions";

zorba-rest:get("http://www.google.com/", 
               (),
               <headers>
                <header name="Referer">http://www.yahoo.com/</header>
               </headers>)

Example 4

(: Complex GET example with parameters and headers :)

import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions";

zorba-rest:get("http://www.example.com/path",
               <payload>
                 <part name="parameter1">value1</part>
                 <part name="parameter2">value2</part>
               </payload>,
               <headers>
                 <header name="Referer">http://www.example2.com/path2</header>
                 <header name="User_agent">ZorbaREST</header>
               </headers>)

REST POST Examples

Example 1

(: Example of zorba-rest:post with string parameters :)

import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions";

zorba-rest:post("http://www.example.com/path",
                <payload content-type="multipart/form-data">
                  <part name="parameter1">value1</part>
                  <part name="parameter2">value2</part>
                </payload>)

Example 2

(: Example of zorba-rest:post with string parameters and custom headers :)

import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions";

zorba-rest:post("http://www.example.com/path",
                <payload content-type="multipart/form-data">
                  <part name="parameter1">value1</part>
                  <part name="parameter2">value2</part>
                </payload>,
                <headers>
                  <header name="custom">custom header value</header>
                 </headers>)

Example 3

(: Example of zorba-rest:post with XML parts and strings as parameters :)

import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions";

zorba-rest:post("http://www.example.com/path",
                <payload content-type="multipart/form-data">
                  <part name="parameter1">value1</part>
                  <part name="parameter2">
                    <data attr="value">
                      <a>text</a>
                      <b>text2</b>
                    </data>
                  </part>
                </payload>)