http://www.zorba-xquery.com/modules/http-client ZC

Module Description
Before using any of the functions below please remember to import the module namespace:
import module namespace http = "http://www.zorba-xquery.com/modules/http-client";

This module provides an interface for zorbas http client. Basically it provides functions for simple http requests (GET, POST, DELETE etc.) and a general purpose function. If the simple functions are not enough powerfull for your needs, you should use the implementation of the EXPath module instead. See the spec of the http-client for more information about EXPaths http-client. While the EXPath functions are all declared as sequential, some functions in this module are defined as nondeterministic. But if you are making a request with one of these functions to a server which does not conform to the HTTP RFC (i.e. which introduces side effects for side-effect free calls like GET), use the EXPath module instead. Otherwise the behavior of your code will be undefined. Zorba has no way to figure out, if a HTTP call is side-effect free or not. Examples of how to use this module: Simple GET Request (retrieving text)

http:get-text( "www.example.com" )
returns
   <response xmlns="http://expath.org/ns/http-client" status="200" message="OK">
     <header name="Content-Type" value="text/html; charset=UTF-8"/>
     <header name="Content-Length" value="574"/>
     ...
     <body media-type="text/html"/>
   </response>
   &lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"&gt;
   &lt;html&gt;
     &lt;head&gt;
       &lt;meta http-equiv="Content-Type"
       content="text/html; charset=utf-8" /&gt;
       &lt;title&gt;Example Web Page</title&gt;
     &lt;/head&gt;
     &lt;body&gt;
       &lt;p&gt;You have reached this web page by typing "example.com",
       "example.net", or "example.org" into your web browser.&lt;/p&gt;
       &lt;p&gt;These domain names are reserved for use in documentation and are
       Not available for registration. See
       &lt;a href="http://www.rfc-editor.org/rfc/rfc2606.txt"&gt;RFC 2606&lt;/a&gt;,
       Section 3.&lt;/p&gt;
     &lt;/body&gt;
   &lt;/html&gt;
   
Simple GET Request (retrieving XHTML)
   declare namespace xhtml="http://www.w3.org/1999/xhtml";
   http:get-node( "www.w3.org" )[2]//xhtml:body
   

This example shows how to retrieve an XHTML resource. Note, that the node test that is looking for the body element in the result requires the xhtml namespace to be specified.

Simple POST Request

Here is a simple example which sends a text content by making an HTTP POST request.

   http:post( "...", "Hello World" )
   
The response of this request can look as follows:
   <http:response status="200" message="Ok">
      <http:header name="Content-Type" value="text/html"/>
      <http:header name="Server" value="Apache ..."/>
      ...
      <http:body content-type="text/html"/>
   </http:response>
 

Author:

Markus Pilman

XQuery version and encoding for this module:

xquery version "3.0" encoding "utf-8";

Module Resources
Module Dependencies

Imported modules:

Imported schemas:

External C++ library dependencies:

Related Documentation

For more details please also see:

Namespaces
ann http://zorba.io/annotations
err http://www.w3.org/2005/xqt-errors
error http://expath.org/ns/error
http http://www.zorba-xquery.com/modules/http-client
http-schema http://expath.org/ns/http-client
ver http://zorba.io/options/versioning
Function Summary
delete ( $href as xs:string ) as item()+
Makes a HTTP DELETE request.
get ( $href as xs:string ) as item()+
This function makes a GET request on a given URL.
get-binary ( $href as xs:string ) as item()+
This function makes a GET request on a given URL.
get-node ( $href as xs:string ) as item()+
This function makes a GET request on a given URL.
get-text ( $href as xs:string ) as item()+
This function makes a GET request on a given URL.
head ( $href as xs:string ) as item()
Makes a HTTP HEAD request.
options ( $href as xs:string ) as xs:string*
Makes a HTTP OPTIONS request.
post ( $href as xs:string, $body as item() ) as item()+
Makes a HTTP POST request.
post ( $href as xs:string, $body as item(), $content-type as xs:string ) as item()+
Makes a HTTP POST request.
put ( $href as xs:string, $body as item() ) as item()+
Makes a HTTP PUT request.
put ( $href as xs:string, $body as item(), $content-type as xs:string ) as item()+
Makes a HTTP PUT request.
send-request ( $request as element(http-schema:request)?, $href as xs:string?, $bodies as item()* ) as item()+
This function sends an HTTP request and returns the corresponding response.
Functions
delete back to 'Function Summary'
declare %ann:sequential function http:delete (
            $href as xs:string 
 ) as item()+

Makes a HTTP DELETE request.

Parameters:
Returns:
Errors:

get back to 'Function Summary'
declare %ann:nondeterministic function http:get (
            $href as xs:string 
 ) as item()+

This function makes a GET request on a given URL. This function just makes a http GET request on $href. The function is nondeterministic. But if a GET request to the given address has side effects, which would not conform with the RFC but is often the case, then you should use a sequential function instead. This functions uses the ContentType of the response to parse the result. It will return a sequence of items, where the first item describes the result according to the expath specification. The next items are the date of each body element. Each body will be:

Unlike the expath http-client, this function will never tidy html to xml.

Parameters:
Returns:
Errors:

get-binary back to 'Function Summary'
declare %ann:nondeterministic function http:get-binary (
            $href as xs:string 
 ) as item()+

This function makes a GET request on a given URL. This function just makes a http GET request on $href. The function is nondeterministic. But if a GET request to the given address has side effects, which would not conform with the RFC but is often the case, then you should use a sequential function instead.

Parameters:
Returns:
Errors:

get-node back to 'Function Summary'
declare %ann:nondeterministic function http:get-node (
            $href as xs:string 
 ) as item()+

This function makes a GET request on a given URL. This function just makes a http GET request on $href. The function is nondeterministic. But if a GET request to the given address has side effects, which would not conform with the RFC but is often the case, then you should use a sequential function instead.

Parameters:
Returns:
Errors:

get-text back to 'Function Summary'
declare %ann:nondeterministic function http:get-text (
            $href as xs:string 
 ) as item()+

This function makes a GET request on a given URL. This function just makes a http GET request on $href. The function is nondeterministic. But if a GET request to the given address has side effects, which would not conform with the RFC but is often the case, then you should use a sequential function instead.

Parameters:
Returns:
Errors:

head back to 'Function Summary'
declare %ann:nondeterministic function http:head (
            $href as xs:string 
 ) as item()

Makes a HTTP HEAD request.

Parameters:
Returns:
Errors:

options back to 'Function Summary'
declare %ann:nondeterministic function http:options (
            $href as xs:string 
 ) as xs:string*

Makes a HTTP OPTIONS request. This request ask for OPTIONS supported of the server.

Parameters:
Returns:
Errors:

post back to 'Function Summary'
declare %ann:sequential function http:post (
            $href as xs:string, 
            $body as item() 
 ) as item()+

Makes a HTTP POST request. This function supports only simple http POST requests which should suite most of the mostly common requests. Unlike the send-request function from the EXPath http client, the user only has to give a URL, where she wants the request sent to and a body as an item. The body will than be serialized as follows:

Parameters:
Returns:
Errors:

post back to 'Function Summary'
declare %ann:sequential function http:post (
            $href as xs:string, 
            $body as item(), 
            $content-type as xs:string 
 ) as item()+

Makes a HTTP POST request. This function supports only simple http POST requests which should suite most of the mostly common requests. Unlike the send-request function from the EXPath http client, the user only has to give a URL, where she wants the request sent to and a body as an item. The body will than be serialized as follows:

Parameters:
Returns:
Errors:

put back to 'Function Summary'
declare %ann:sequential function http:put (
            $href as xs:string, 
            $body as item() 
 ) as item()+

Makes a HTTP PUT request.

Parameters:
Returns:
Errors:

put back to 'Function Summary'
declare %ann:sequential function http:put (
            $href as xs:string, 
            $body as item(), 
            $content-type as xs:string 
 ) as item()+

Makes a HTTP PUT request. This function takes the content type as a third parameter. Note that this content type is used to determine the serialization, if the second argument is an element node. If this automatic process does not work, use fn:serialize instead.

Parameters:
Returns:
Errors:

send-request back to 'Function Summary'
declare %ann:sequential function http:send-request (
            $request as element(http-schema:request)?, 
            $href as xs:string?, 
            $bodies as item()* 
 ) as item()+

This function sends an HTTP request and returns the corresponding response. It just implements the http:send-request/3 function from the EXPath module. To provide better interoperability between XQuery engines, use the EXPath module instead.

This function is declared as sequential (see XQuery Scripting). Sequential functions are allowed to have side effects. For example, most probably, an HTTP POST request is a request that has side effects because it adds/changes a remote resource.

Parameters:
Returns:
Errors: