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
4 Dealing with the response
4.1 The result element
4.2 Representing the result content
Error conditions are identified by a code (a
QName.) When such
an error condition is reached in the evaluation of an expression, an dynamic
error is thrown, whith the corresponding error code (as if the standard XPath
error had been called.) TODO: Have not been defined yet.
$content is the request body content, for HTTP methods that can
contain a body in the request (POST and PUT.) This is an error if
this param is not the empty sequence for other methods (DELETE, GET,
HEAD and OPTIONS.)
$request contains the various parameters of the request, for instance
the HTTP method to use or the HTTP headers. Among other things, it
can also contain the other param's values: the URI, the content and
the serialization option. If they are not set as parameter to the
function, their value in $request, if any, is used instead. See the
following section for the detailed definition of the http:request
$serial defines the serialization option to serialize the content to
the HTTP request. It can be either a serialization method (a string,
either 'xml', 'html', 'xhtml' or 'text') or an xsl:output element.
The content is then serialized accordingly to the choosen method or
xsl:output regarding [XSLT and XQuery Serialization].
The function defined in this module makes 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.
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
status-only control how the response will look like; if it is
true, only the status code and the headers are returned, the content is not
(no http:body nor http:multipart, nor the interpreted additional value in the
returned sequence, see hereafter.)
http:body represents a multi-part body, either in a request
or a response, as defined below. It can be overriden by the parameter
$content (the way
$content is used to build the
body can be controled by the parameter
$serial, see section
below for details.)
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.
id attribute specifies the value of the HTTP header
description the value of the HTTP header
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
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.)
If the request can have content (one body or several body parts,) it can be
specified by the
http:multipart element, the
element, and/or the parameter
is not the empty sequence, it replaces the value of the
element (in multipart, if there are several bodies, exactly one
must be empty.) For each body, the content of the HTTP body is generated as follow.
content-type is not an XML media type, the string value of the
http:body element is used. If this is an XML media type, it is
serialized using the parameter
$serial. This parameter can be an
xsl:output element, as defined in [XSLT 2.0], and the
serialization is defined in [XSLT and XQuery Serialization].
also be a string, either '
text' (other values are implementation-defined, as explained in
the above mentioned recommendations.) (TODO:
$serial could be a function
item too, when EXSLT will have defined the corresponding module.) The default
value for this parameter depends on the
content-type of the body
('xml', 'html' and 'xhtml' are the default for corresponding media types, and
'text' for other media types.)
HTTP authentication when sending a request is controled by the attributes
send-authorization on the element
username has a value,
auth-method must have a value too. And if any one of the three
other attributes have been set,
username must be set too.
auth-method can be either "
Digest", but other values can also be used, in an
implementation-defined way. The handling of those attributes must be done
in conformance to [RFC 2617]. If
is true (default value is false) and the authentication method supports
generating the header
Authorization without challenge, the
request contains this header. The default value is to send a non-authenticated
request, and if the response is an authentication challenge, then only send
the credentials in a second message.
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.
This is the first item returned by the function defined in this module.
status attribute is the HTTP status code returned by the
http:header elements are as defined for the
request, but represent instead the response headers. The
http:multipart elements are also like in the request, but
http:body elements must be empty.
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:body elements. For each body, the way this item
is built from the HTTP response is as follow.
status-only attribute has the value
false,) the returned sequence will only contain the
http:response element (with the headers, but also the empty
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 textual type, the item is a string, cointaining 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 (TODO: define tidying up) and the item is the resulting document node. For other media types, 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.