REST

1 Introduction

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, POST, PUT, HEAD and DELETE requests. We'll add additional functions 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).

2 Configuring

2.1 HTTPS note

Please make sure to read the HTTPS support from the build instructions.

2.2 Proxy note

If you have a Proxy installed cURL allows you to configure proxy settings using environment variables. Set the following environment variable according to your settings:

http_proxy=http://username:password@proxyserver.example.org:8123/

3 REST Functions

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

3.1 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);

3.1.1 GetTidy Functions

Tidy functions allow parsing HTML imput that is not valid XML. In order to use the functions that require Tidy you have to:

 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:

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:

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

3.2 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);

3.3 PUT 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);

3.4 HEAD Functions

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

3.5 DELETE Functions

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

3.6 Parameter Descriptions

3.3.1 URL

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

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

3.3.3 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>

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

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

3.4 REST Examples

3.4.1 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>)

3.4.2 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>)