-
XQuery Libraries
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 (see
XQuery 1.1), which
means that several calls may return different results.
HTTP requests performed using these functions are not allowed to have
side effects.
For all functions (except read with one parameter),
the request is represented by an http:request
element, specifying the URI, the HTTP method, the headers, and the body
content (for POST and PUT methods) of the HTTP request to make.
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.
http:read( "www.example.com" )
returns
<response xmlns="http://expath.org/ns/http-client" status="200" message="OK">
<header name="Content-Type" value="text/html; charset=UTF-8"/>
<header name="Content-Length" value="574"/>
...
<body media-type="text/html"/>
</response>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=utf-8" />
<title>Example Web Page</title>
</head>
<body>
<p>You have reached this web page by typing "example.com",
"example.net", or "example.org" into your web browser.</p>
<p>These domain names are reserved for use in documentation and are
Not available for registration. See
<a href="http://www.rfc-editor.org/rfc/rfc2606.txt">RFC 2606</a>,
Section 3.</p>
</body>
</html>
Simple GET Request (retrieving XHTML)
declare namespace xhtml="http://www.w3.org/1999/xhtml";
http:read( <http:request href="www.w3.org" method="get"/>, () )[2]//xhtml:body
This example shows how to retrieve an XHTML resource. Note, that the node test that is looking for the body element in the result requires the xhtml namespace to be specified.
Simple POST RequestHere is a simple example which sends a text content by making an HTTP POST request.
http:send-request(
<http:request href="..." method="post">
<http:body content-type="text/plain">
Hello, world!
</http:body>
</http:request>
)
The response of this request can look as follows:
<http:response status="200" message="Ok">
<http:header name="Content-Type" value="text/html"/>
<http:header name="Server" value="Apache ..."/>
...
<http:body content-type="text/html"/>
</http:response>
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
| check-params($request as element(https:request)?, $href as xs:string?, $bodies as item()*) as xs:boolean | |
| create-body($body as element(https:body)) as element(https:body) | |
| create-multipart($multipart as element(https:multipart)) as element(https:multipart) | |
| read($href as xs:string) as item()+ | |
| read($request as element(https:request)?, $href as xs:string?) as item()+ | |
| read($request as element(https:request)?, $href as xs:string?, $bodies as item()*) as item()+ | |
|
send-request($request as element(https:request)) as item()+ |
|
|
send-request($request as element(https:request)?, $href as xs:string?) as item()+ |
|
|
send-request($request as element(https:request)?, $href as xs:string?, $bodies as item()*) as item()+ |
| set-content-type($request as element(https:request)?) as element(https:request)? |
declare sequential function http:send-request (
$request as element(https:request)?,
$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.
declare sequential function http:send-request (
$request as element(https:request)
) 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.
declare sequential function http:send-request (
$request as element(https:request)?,
$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.
declare function http:read (
$request as element(https:request)?,
$href as xs:string?,
$bodies as item()*
) as item()+
This function sends an HTTP request and returns the corresponding response.
This function is not sequential. It is used for retrieving resources and may only be used to send requests which are known to have no side effects, i.e., usually GET or HEAD.
$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.) |
$bodies
|
- | 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.
declare function http:read (
$request as element(https:request)?,
$href as xs:string?
) as item()+
Function for convenience.
Calling this function is equivalent to calling
http:read($request, $href, ())
$request
|
- | see parameter $request of read with three parameters |
$href
|
- | see parameter $href of read with three parameters |
see return of read with three parameters
documentation of read with three parameters.
declare function http:read (
$href as xs:string
) as item()+
Function for convenience.
Calling this function is equivalent to calling
http:read((), $href, ())
$href
|
- | see parameter $href of read with three parameters |
see return of read with three parameters
documentation of read with three parameters.
declare function http:create-body (
$body as element(https:body)
) as element(https:body)
Helper function. This function takes an https:body element, copies it, and adds a method attribute to the copy if there is none in the original element.
$body
|
- | is the original https:body element |
a https:body element with a corresponding @method attribute
declare function http:create-multipart (
$multipart as element(https:multipart)
) as element(https:multipart)
Helper function. This function takes an https:multipart element, copies it and adds a @method attribute to all body elements which don't have one.
$multipart
|
- | the original https:multipart |
a copy of $multipart with all $multipart/body/@method set
declare function http:set-content-type (
$request as element(https:request)?
) as element(https:request)?
Helper function. This adds a default method attribute to all body elements which don't contain a method attribute.
$request
|
- | The request which need to be copied. |
A copy of $request with all request//body/@method set.
declare function http:check-params (
$request as element(https:request)?,
$href as xs:string?,
$bodies as item()*
) as xs:boolean
Private helper function used internally by this module. This function checks if the request, href, and bodies parameters are consistent.
$request
|
- | The request which needs to be checked. |
$href
|
- | The href which needs to be checked. |
$bodies
|
- | The bodies element which needs to be checked. |
true if the parameters are consistent. Otherwise, this function raises an error.