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 blog feed from Zorba:

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

You can try this example live.

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.

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

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