EXSLT 2.0 module - HTTP client

Candidate 2 March 2009

This version:
Latest version:
Previous version:
Florent Georges, fgeorges.org


This proposal provides an HTTP client interface for XSLT 2.0. It defines one extension function to perform HTTP requests, and has been designed to be compatible with XQuery and XPath 2.0.

Table of Contents

1 Introduction
    1.1 Namespace conventions
    1.2 Error management
2 The http:send-request function
3 Sending a request
    3.1 The request elements
    3.2 Serializing the request content
    3.3 Authentication
4 Dealing with the response
    4.1 The result element
    4.2 Representing the result content
5 Content types handling


A References

1 Introduction

2 The http:send-request function

This module defines an XPath extension function that sends an HTTP request and return the corresponding response. It supports HTTP multi-part messages. Here is the signature of this function:

Besides the 4-params signature above, there are 3 other signatures that are convenient shortcuts (corresponding to the full version in which corresponding params have been set to the empty sequence.) They are:

http:send-request($request as element(http:request)) as item()+
http:send-request($uri as xs:string?,
                  $request as element(http:request)?) as item()+
http:send-request($uri as xs:string?,
                  $request as element(http:request)?,
                  $content as item()?) as item()+

3 Sending a request

The functions defined in this module make one able to send a request to an HTTP server and receive the corresponding response. Here is how the request is represented by the parameters to this function, and how they are used to generate the actual HTTP request to send.

3.1 The request elements

The http:request element represents all the needed information to send the HTTP request. So it is always possible to create such an element that will carry over all the needed info for a particular request. For some of those values though, you can use an additional param instead. For instance, some signatures define the parameter $uri. If the value of this parameter is not the empty sequence, it will then be used instead of the value of the attribute href on the http:request element.

The http:header element represents an HTTP header, either in a request or in a response.

The http:body element represents the body of either an HTTP request or of an HTTP response (in multi-part requests and responses, it represents the body of a single one part.)

The content-type and encoding attributes are used to control the way the content of this element is used to create the HTTP request (how it is serialized to the request content.) See section below for details. The id attribute specifies the value of the HTTP header Content-ID and description the value of the HTTP header Content-Description. The href attribute can be used in a request to set the body content as the content of the linked resource instead of using the children of the http:body element (children of this element and the href attribute are mutually exclusive.)

The http:multipart element represents an HTTP multi-part request or response. The content-type attribute is the media type of the whole request or response, and has to be a multipart media type (that is, its main type must be multipart.) The boundary attribute is the boundary marker used to separate the several parts in the message (the value of the attribute is prefixed with "--" to form the actual boundary marker in the request; on the other way, this prefix is removed from the boundary marker in the response to set the value of the attribute.)

3.2 Serializing the request content

If the request can have content (one body or several body parts,) it can be specified by the http:multipart element, the http:body element, and/or the parameter $content. If $content is not the empty sequence, it replaces the value of the http:body element (in multipart, if there are several bodies, exactly one http:body must be empty.) For each body, the content of the HTTP body is generated as follow.

The parameter $serial is used to control the way the content is serialized. This parameter can be an xsl:output element, as defined in [XSLT 2.0], and the serialization is defined in [Serialization]. $serial can also be a string, either 'xml', 'html', 'xhtml' or 'text' (other values are implementation-defined, as explained in the above mentioned recommendations.) (Note: $serial should be able to be a function item too, when EXSLT will have defined the corresponding module.) If $serial is the empty sequence, the default value for this parameter depends on the content-type of the body: it is 'xml' if it is an XML media type, 'html' if it is an HTML media type, 'xhtml' if it is application/xhtml+xml or 'text' for any other case.

4 Dealing with the response

After having sent the request to the HTTP server, the function waits for the response. It analyses it and returns a sequence representing this response. This sequence has an http:response element as first item, which is followed be an additional item for each body or body part in the response.

4.2 Representing the result content

Instead of being inserted within the http:response element, the content of each body is returned as a single item in the return sequence. Each item is in the same order (after the http:response element) than the http:body elements. For each body, the way this item is built from the HTTP response is as follow.

If the status-only attribute has the value true (default is false,) the returned sequence will only contain the http:response element (with the headers, but also the empty http:body or http:multipart elements, as if status-only was false,) and the following items, representing the bodies content are not generated from the HTTP response.

For each body that has to be interpreted, the following rules apply in order to build the corresponding item. If the body media type is a text media type, the item is a string, containing the body content. If the media type is an XML media type, the content is parsed and the item is the resulting document node. If the media type is an HTML type, the content is tidied up and parsed (this process is implementation-dependant) and the item is the resulting document node. If this is a binary media type, the content is returned as a base64Binary item. From the previous rules, a result item can then be either a document node (from XML or HTML,) a string or a base64Binary.

If the attribute override-content-type is set on the request, its value is used instead of the content-type returned by the HTTP server (TODO: how does it fit with multipart responses?)

5 Content types handling

In both requests and responses, MIME type strings are used to choose the way the entity content has to be respectively serialized or parsed. Four different kinds of type are defined here, which are used in the above text about sending request and receiving response. The intent is to provide the spirit of the entity content handling regarding its content type, but an implementation is encouraged to deviate from those rules if it is obvious that a particular type should be treated in a specific way (normally, that would be the case only to treat a binary type as another type.)

A References

The structure of most of the elements and most of the attributes used in this candidate are inspired from the corresponding step in [XProc].

HTML Tidy Library Project. SourceForge project.
RFC 1521
RFC 1521: MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies. N. Borenstein, N. Freed, editors. Internet Engineering Task Force. September, 1993.
RFC 2616
RFC 2616: Hypertext Transfer Protocol — HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, et. al., editors. Internet Engineering Task Force. June, 1999.
RFC 2617
RFC 2617: HTTP Authentication: Basic and Digest Access Authentication. J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart. June, 1999.
RFC 3023
RFC 3023: XML Media Types. M. Murata, S. St. Laurent, and D. Kohn, editors. Internet Engineering Task Force. January, 2001.
XSLT 2.0 and XQuery 1.0 Serialization. Scott Boag, Michael Kay, Joanne Tong, Norman Walsh, and Henry Zongaro, editors. W3C Recommendation. 23 January 2007.
TagSoup - Just Keep On Truckin'. John Cowan.
XProc: An XML Pipeline Language. N. Walsh, A. Milowski, and H. S. Thompson, editors. W3C Candidate Recommendation. 26 November 2008.
XSLT 2.0
XSL Transformations (XSLT) Version 2.0. Michael Kay, editor. W3C Recommendation. 23 January 2007.