http://expath.org/ns/http-client

import module namespace http = "http://expath.org/ns/http-client";

This module provides an implementation of the EXPath Http Client. It provides functions for making HTTP requests and is a superset of the module specified by EXPath. Specifically, it implements the http:send-request() functions as specified by EXPath. Moreover, it adds an additional function http:read() (with several arities for the sake of ease).

In general, both functions take a description of the HTTP request to make as parameter, execute the request, and return a representation of the HTTP response.

The http:send-request() functions are declared as sequential. 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. Sequential functions are specified in the XQuery Scripting Extension, which is an extension of XQuery. Sequential functions are only allowed to be invoked in certain places (e.g. only from functions which are declared as sequential themselves). In contrast, the http:read() functions are not declared as sequential - they are declared as nondeterministic though, which means that several calls may return different results. HTTP requests performed using these functions are not allowed to have side effects.

The response is returned as a sequence of one or more items. The first one is an http:response element with quite the same structure as an http:request, but without the content itself. The content is returned as the second item (or several items in case of a multipart response) as a string, a document node, or a binary item. This depends on the content-type returned. Specifically, the rules are as follows:

• A document node is returned if the media type has a MIME type of text/xml, application/xml, text/xml-external-parsed-entity, or application/xml-external-parsed-entity, as defined in [RFC 3023] (except that application/xml-dtd is considered a text media type). MIME types ending by +xml are also XML media types.
• A document node is returned if the media type has a MIME type of text/html. In order to be able to make HTML parseable, tidy is automatically invoked. If you want to prevent that, you can also set your own content-type by setting the override-media-type attribute in the request element. For tidying, the following options will be used:
  • TidyXmlOut=yes
  • TidyDoctypeMode=TidyDoctypeOmit
  • TidyQuoteNbsp=yes
  • TidyCharEncoding="utf8"
  • TidyNewline="LF"
• An xs:string item is returned if the media type has a text MIME type, i.e. beginning with text/.
• An xs:base64Binary item is returned for all the other media types.

The structure of a request element is defined in the schema that is imported by this module. The details are described in the specification. Analogously, the response element is also described in this specification.

Markus Pilman

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

• the XQuery module can be found here.

Imported modules:

• http://www.zorba-xquery.com/modules/http-client
• http://expath.org/ns/error
• http://www.zorba-xquery.com/modules/converters/html

Imported schemas:

• http://www.zorba-xquery.com/modules/converters/html-options
• http://expath.org/ns/http-client

External C++ library dependencies:

• cURL Library

For more details please also see:

• XQuery 1.1: Function Declaration

	send-request ( $request as element(*) ) as item()+ Function for convenience.
	send-request ( $request as element(*)?, $href as xs:string? ) as item()+ Function for convenience.
	send-request ( $request as element(*)?, $href as xs:string?, $bodies as item()* ) as item()+ This function sends an HTTP request and returns the corresponding response.

send-request

declare %ann:sequential function http:send-request (
            $request as element(*) 
 ) as item()+

Function for convenience. Calling this function is equivalent to calling http:send-request($request, (), ())

• $request see request parameter of the sequential send-request function with three parameters.

• see return value of the sequential send-request function with three parameters.

• documentation of send-request with three parameters.

send-request

declare %ann:sequential function http:send-request (
            $request as element(*)?, 
            $href as xs:string? 
 ) as item()+

Function for convenience. Calling this function is equivalent to calling http:send-request($request, $href, ())

• $request see request parameter of the sequential send-request function with three parameters.
• $href see href parameter of the sequential send-request function with three parameters.

• see return of send-request

• documentation of send-request with three parameters.

send-request

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

This function sends an HTTP request and returns the corresponding response.

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.

• $request Contains the various parameters of the request. See the specification. for a full description of the structure of this element.
• $href is the HTTP or HTTPS URI to send the request to. It must be a valid xs:anyURI, but is declared as a string to be able to pass literal strings (without requiring to explicitly cast it to an xs:anyURI.)
• $content is the request body content, for HTTP methods that can contain a body in the request (i.e. POST and PUT). It is an error, if this param is not the empty sequence for methods other then DELETE, GET, HEAD and OPTIONS.

• a sequence of items, where the first item is a element of type http:responseType. The response element is also described in the specification. If there is one (or several, in case of multipart) response body, the response bodies are the next items in the sequence.