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 and POST requests. We'll add additional functions for HEAD, DELETE, and PUT 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 zorba-rest:result;
 declare nondeterministic sequential function zorba-rest:get(url as xs:string, payload as zorba-rest:payload*) as zorba-rest:result;
 declare nondeterministic sequential function zorba-rest:get(url as xs:string, payload as zorba-rest:payload*, 
                                                             headers as zorba-rest:headers*) as zorba-rest:result;

POST Functions

 declare nondeterministic sequential function zorba-rest:post(url as xs:string) as zorba-rest:result;
 declare nondeterministic sequential function zorba-rest:post(url as xs:string, payload as zorba-rest:payload*) as zorba-rest:result;
 declare nondeterministic sequential function zorba-rest:post(url as xs:string, payload as zorba-rest:payload*, 
                                                              headers as zorba-rest:headers*) as 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 2

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

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

Example 3

(: 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 4

(: 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 5

(: 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>)