1. Zorba 3.0 Documentation
  2. Modules
  3. EXPath
  4. HTTP

http://expath.org/ns/http-client

View as XML or JSON.

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 Zorba home page: 

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

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.

Function Summary

send-request ($request as element(*)) as item()+

Function for convenience.
send-request ($request as element(*)?, $href as xs:string?) as item()+

Function for convenience.
send-request ($request as element(*)?, $href as xs:string?, $bodies as item()*) as item()+

This function sends an HTTP request and returns the corresponding response.

Functions

send-request#1

declare  %an:sequential function http:send-request($request as element(*)) as item()+
Function for convenience. Calling this function is equivalent to calling http:send-request($request, (), ())

Parameters

request as element(*)
see request parameter of the sequential send-request function with three parameters.

Returns

item()+
see return value of the sequential send-request function with three parameters.

send-request#2

declare  %an:sequential function http:send-request($request as element(*)?, $href as xs:string?) as item()+
Function for convenience. Calling this function is equivalent to calling http:send-request($request, $href, ())

Parameters

request as element(*)
see request parameter of the sequential send-request function with three parameters.
href as xs:string
see href parameter of the sequential send-request function with three parameters.

Returns

item()+
see return of send-request

send-request#3

declare  %an:sequential function http:send-request($request as element(*)?, $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.

Parameters

request as element(*)
Contains the various parameters of the request. See the specification. for a full description of the structure of this element.
href as xs:string
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 as item()

Returns

item()+
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.