REST

• Table of Contents
  • 1 Introduction
  • 2 Configuring
    • 2.1 HTTPS note
    • 2.2 Proxy note
  • 3 REST Functions
    • 3.1 GET Functions
      • 3.1.1 GetTidy Functions
    • 3.2 POST Functions
      • 3.2.1 PostTidy Functions
    • 3.3 PUT Functions
    • 3.4 HEAD Functions
    • 3.5 DELETE Functions>
    • 3.6 Parameter Descriptions
      • 3.3.1 URL
      • 3.3.2 Payload
      • 3.3.3 Headers
      • 3.3.4 Result
      • 3.3.5 Errors
    • 3.4 REST Examples
      • 3.4.1 Rest examples on Try Zorba site
      • 3.4.2 REST GET Examples

      • 3.4.2 REST POST Examples

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:

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

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.2.1 PostTidy Functions

 declare nondeterministic sequential function zorba-rest:postTidy( 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);

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 examples on Try Zorba site

Please check out the examples with the Rest functions from Try Zorba site.

3.4.2 REST GET Examples

Example 1

(: Simple rest-get example :)

import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions"; 
let $result := zorba-rest:get("http://tidy.sourceforge.net/docs/quickref.html")

let $payload := $result//zorba-rest:payload
return  $payload 

Example 2

(: rest-getTidy example using Tidy options  :)

import module namespace zorba-rest = "http://www.zorba-xquery.com/zorba/rest-functions"; 
let $result := zorba-rest:getTidy('http://tidy.sourceforge.net/docs/quickref.html','"newline=CRLF","doctype=omit","force-output","bare=yes"')

let $payload := $result//zorba-rest:payload
return  $payload 

Example 3

(: rest-getTidy example using payload and Tidy options :)

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

let $tmp := zorba-rest:getTidy("http://www.google.com/search",
  '"newline=CRLF","doctype=omit","force-output","bare=yes"',
  <payload>
    <part name="q">zorba xquery</part>
  </payload>)

return $tmp//zorba-rest:status-code

Example 4

(: rest-getTidy example using payload, headers and Tidy options :)

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

let $tmp := zorba-rest:getTidy("http://www.google.com/search",
  '"newline=CRLF","doctype=omit","force-output","bare=yes"',
  <payload>
    <part name="q">zorba xquery</part>
  </payload>,
  <headers>
    <header name="Referer">http://www.yahoo.com/</header>
  </headers>)

return $tmp//zorba-rest:status-code

3.4.2 REST POST Examples

Example 1

(: Simple rest-postTidy example :)

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

let $result := zorba-rest:postTidy('http://tidy.sourceforge.net/docs/quickref.html','"newline=CRLF","doctype=omit","force-output","bare=yes"', (), ()) 

let $payload := $result//zorba-rest:payload
return  $payload