- Function Index
- www.w3.org
- XDM
- store
- introspection
- reflection
- external
-
xqdoc
-
xqdoc
(E)
-
project_xqdoc
- xqdoc2xhtml
-
xqdoc
(E)
-
data processing
- data cleaning
- data converters
- data formatting
- programming languages
- excel
- cryptography
- geo
- image
- OAuth
- expath.org
- www.functx.com
- communication
- error
-
XQuery Modules Documentation
http://www.zorba-xquery.com/modules/http-client
import module namespace http = "http://www.zorba-xquery.com/modules/http-client";
This module provides an interface for zorbas http client. Basically it provides functions for simple http requests (GET, POST, DELETE etc.) and a general purpose function. If the simple functions are not enough powerfull for your needs, you should use the implementation of the EXPath module instead. See the spec of the http-client for more information about EXPaths http-client. While the EXPath functions are all declared as sequential, some functions in this module are defined as nondeterministic. But if you are making a request with one of these functions to a server which does not conform to the HTTP RFC (i.e. which introduces side effects for side-effect free calls like GET), use the EXPath module instead. Otherwise the behavior of your code will be undefined. Zorba has no way to figure out, if a HTTP call is side-effect free or not. Examples of how to use this module: Simple GET Request (retrieving text)
http:get-text( "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:get-node( "www.w3.org" )[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:post( "...", "Hello World" )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>
Markus Pilman
xquery version "
- the XQuery module can be found here.
- the implementation of the external functions can be found here.
Imported modules:
Imported schemas:
External C++ library dependencies:
For more details please also see:
ann | http://zorba.io/annotations |
err | http://www.w3.org/2005/xqt-errors |
error | http://expath.org/ns/error |
http | http://www.zorba-xquery.com/modules/http-client |
http-schema | http://expath.org/ns/http-client |
ver | http://zorba.io/options/versioning |
![]() |
delete
(
$href as xs:string
) as item()+ Makes a HTTP DELETE request. |
![]() |
get
(
$href as xs:string
) as item()+ This function makes a GET request on a given URL. |
![]() |
get-binary
(
$href as xs:string
) as item()+ This function makes a GET request on a given URL. |
![]() |
get-node
(
$href as xs:string
) as item()+ This function makes a GET request on a given URL. |
![]() |
get-text
(
$href as xs:string
) as item()+ This function makes a GET request on a given URL. |
![]() |
head
(
$href as xs:string
) as item() Makes a HTTP HEAD request. |
![]() |
options
(
$href as xs:string
) as xs:string* Makes a HTTP OPTIONS request. |
![]() |
post
(
$href as xs:string,
$body as item()
) as item()+ Makes a HTTP POST request. |
![]() |
post
(
$href as xs:string,
$body as item(),
$content-type as xs:string
) as item()+ Makes a HTTP POST request. |
![]() |
put
(
$href as xs:string,
$body as item()
) as item()+ Makes a HTTP PUT request. |
![]() |
put
(
$href as xs:string,
$body as item(),
$content-type as xs:string
) as item()+ Makes a HTTP PUT request. |
![]() |
send-request
(
$request as element(http-schema:request)?,
$href as xs:string?,
$bodies as item()*
) as item()+ This function sends an HTTP request and returns the corresponding response. |
declare %ann:sequential function http:delete (
$href as xs:string
) as item()+
Makes a HTTP DELETE request.
- $href The URL where to send the request.
- The first element of the result is the metadata (like headers, status etc), the next elements are the response
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:nondeterministic function http:get (
$href as xs:string
) as item()+
This function makes a GET request on a given URL. This function just makes a http GET request on $href. The function is nondeterministic. But if a GET request to the given address has side effects, which would not conform with the RFC but is often the case, then you should use a sequential function instead. This functions uses the ContentType of the response to parse the result. It will return a sequence of items, where the first item describes the result according to the expath specification. The next items are the date of each body element. Each body will be:
-
an element node, if the returned content type is one of:
- text/xml
- application/xml
- text/xml-external-parsed-entity
- application/xml-external-parsed-entity
- or if the Content-Type ends with "+xml"
- A text node, if the content type starts with "text/" and does not match the strings for xml.
- for all other content types the type will be xs:base64Binary
- $href The URL to which the call will be made.
- 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.
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:nondeterministic function http:get-binary (
$href as xs:string
) as item()+
This function makes a GET request on a given URL. This function just makes a http GET request on $href. The function is nondeterministic. But if a GET request to the given address has side effects, which would not conform with the RFC but is often the case, then you should use a sequential function instead.
- $href The URL to which the call will be made.
- 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.
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:nondeterministic function http:get-node (
$href as xs:string
) as item()+
This function makes a GET request on a given URL. This function just makes a http GET request on $href. The function is nondeterministic. But if a GET request to the given address has side effects, which would not conform with the RFC but is often the case, then you should use a sequential function instead.
- $href The URL to which the call will be made.
- 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.
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:nondeterministic function http:get-text (
$href as xs:string
) as item()+
This function makes a GET request on a given URL. This function just makes a http GET request on $href. The function is nondeterministic. But if a GET request to the given address has side effects, which would not conform with the RFC but is often the case, then you should use a sequential function instead.
- $href The URL to which the call will be made.
- 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.
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:nondeterministic function http:head (
$href as xs:string
) as item()
Makes a HTTP HEAD request.
- $href The URL to which the request will be made.
- A element which describes the result of this request. A http HEAD request never returns a body.
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:nondeterministic function http:options (
$href as xs:string
) as xs:string*
Makes a HTTP OPTIONS request. This request ask for OPTIONS supported of the server.
- $href The URL where to send the request.
- A sequence of string with the allowed operations
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:sequential function http:post ( $href as xs:string, $body as item() ) as item()+
Makes a HTTP POST request. This function supports only simple http POST requests which should suite most of the mostly common requests. Unlike the send-request function from the EXPath http client, the user only has to give a URL, where she wants the request sent to and a body as an item. The body will than be serialized as follows:
- If $body is of type xs:string, it will be serialized as plain text and the Content-Type for the request will be set to "text/plain"
- If $body is an element node, the Content-Type will be set to "text/xml" and the element will be serialized as xml.
- $href The URL where to send the request.
- $body The body which will be sent to the server
- The first element of the result is the metadata (like headers, status etc), the next elements are the response
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:sequential function http:post ( $href as xs:string, $body as item(), $content-type as xs:string ) as item()+
Makes a HTTP POST request. This function supports only simple http POST requests which should suite most of the mostly common requests. Unlike the send-request function from the EXPath http client, the user only has to give a URL, where she wants the request sent to and a body as an item. The body will than be serialized as follows:
- If $body is of type xs:string, it will be serialized as plain text and the Content-Type for the request will be set to "text/plain"
- If $body is an element node, the Content-Type will be set to "text/xml" and the element will be serialized as xml.
- $href The URL where to send the request.
- $body The body which will be sent to the server
- $content-type The content type of the body.
- The first element of the result is the metadata (like headers, status etc), the next elements are the response
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:sequential function http:put ( $href as xs:string, $body as item() ) as item()+
Makes a HTTP PUT request.
- $href The URL where to send the request.
- $body The body which will be sent to the server
- The first element of the result is the metadata (like headers, status etc), the next elements are the response
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:sequential function http:put ( $href as xs:string, $body as item(), $content-type as xs:string ) as item()+
Makes a HTTP PUT request. This function takes the content type as a third parameter. Note that this content type is used to determine the serialization, if the second argument is an element node. If this automatic process does not work, use fn:serialize instead.
- $href The URL where to send the request.
- $body The body which will be sent to the server
- $content-type The content type of the body.
- The first element of the result is the metadata (like headers, status etc), the next elements are the response
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.
declare %ann:sequential function http:send-request ( $request as element(http-schema:request)?, $href as xs:string?, $bodies as item()* ) as item()+
This function sends an HTTP request and returns the corresponding response. It just implements the http:send-request/3 function from the EXPath module. To provide better interoperability between XQuery engines, use the EXPath module instead.
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.
- err:XPST0081 Schema validation error - this happens whenever a wrong request element is given.
- error:HC001 An HTTP error occurred.
- error:HC002 Error parsing the entity content as XML or HTML.
- error:HC003 With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
- error:HC004 The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
- error:HC005 The request element is not valid.
- error:HC006 A timeout occurred waiting for the response.