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

Description

Before using any of the functions below please remember to import the module namespace:

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. For instance, in the following code snippet, we fetch the Zorba home page: 

import module namespace http = "http://expath.org/ns/http-client";
 http:send-request(
  <http:request href="http://zorba.io" method="get" />
 )

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

Module code

Here is the actual XQuery module code.

Imported Schemas

Please note that the schemas are not automatically imported in the modules that import this module.

In order to import and use the schemas, please add:

import schema namespace tidy-options =  "http://www.zorba-xquery.com/modules/converters/html-options";
import schema namespace https =  "http://expath.org/ns/http-client";

Imported modules

See also

Authors

Federico Cavalieri, Markus Pilman

Version Declaration

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

Namespaces

anhttp://zorba.io/annotations
errhttp://expath.org/ns/error
httphttp://expath.org/ns/http-client
http-wrapperhttp://zorba.io/modules/http-client-wrapper
httpshttp://expath.org/ns/http-client
tidyhttp://www.zorba-xquery.com/modules/converters/html
tidy-optionshttp://www.zorba-xquery.com/modules/converters/html-options
verhttp://zorba.io/options/versioning

Function Summary

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($request as element(*)) as item()+

Function for convenience.

send-request($request as element(*)?, $href as xs:string?) as item()+

Function for convenience.

tidy-result($result as item()+, $override-media-type as xs:string?) as item()+

Functions

send-request#3

declare %an: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.

Parameters

  • $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.

Returns

  • item()+

    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.

send-request#1

declare %an:sequential function http:send-request(
    $request as element(*)
) as item()+
Function for convenience. Calling this function is equivalent to calling http:send-request($request, (), ())

Parameters

  • $request

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

Returns

  • item()+

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

send-request#2

declare %an: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, ())

Parameters

  • $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.

Returns

  • item()+

    see return of send-request

tidy-result#2

declare %:private function http:tidy-result(
    $result as item()+,
    $override-media-type as xs:string?
) as item()+

Returns

  • item()+