Namespaces and Prefixes

All functions and errors in this module are assigned to the http://expath.org/ns/http-client namespace. In this document, the http prefix is bound to this URI.

HTTP 1.0 Support

This module supports all features of HTTP 1.0. Although we do not provide explicit functions for the LINK and UNLINK HTTP methods, as in practice these methods do not appear to be widely used, they are still supported via the http:send function.

HTTP/2 Support

We acknowledge that HTTP/2 support is currently in its infancy. We have attempted to design for a future version of this specification to extend control for HTTP/2 via extension points such as $options and further arity functions. We await feedback from the users of this specification, with regards to revisions for further support of HTTP/2 features.

http:get

http:get($uri as xs:string) as map(xs:string, item())
http:get($uri as xs:string, $options as map(xs:string, item())) as map(xs:string, item())

Sends a GET request to the supplied $uri and returns the response as a map. Additional $options can be supplied.

http:post

http:post($uri as xs:string, $body as item()*) as map(xs:string, item())
http:post($uri as xs:string, $body as item()*, $options as map(xs:string, item())) as map(xs:string, item())

Sends a POST request with an optional $body to the supplied $uri and returns the response as a map. Additional $options can be supplied.

http:put

http:put($uri as xs:string, $body as item()*) as map(xs:string, item())
http:put($uri as xs:string, $body as item()*, $options as map(xs:string, item())) as map(xs:string, item())

Sends a PUT request with an optional $body to the supplied $uri and returns the response as a map. Additional $options can be supplied.

http:delete

http:delete($uri as xs:string) as map(xs:string, item())
http:delete($uri as xs:string, $options as map(xs:string, item())) as map(xs:string, item())

Sends a DELETE request to the supplied $uri and returns the response as a map. Additional $options can be supplied.

http:head

http:head($uri as xs:string) as map(xs:string, item())
http:head($uri as xs:string, $options as map(xs:string, item())) as map(xs:string, item())

Sends a HEAD request to the supplied $uri and returns the response as a map. Additional $options can be supplied.

http:options

http:options($uri as xs:string) as map(xs:string, item())
http:options($uri as xs:string, $options as map(xs:string, item())) as map(xs:string, item())

Sends an OPTIONS request to the supplied $uri and returns the response as a map. Additional $options can be supplied.

http:trace

http:trace($uri as xs:string, $body as item()*) as map(xs:string, item())
http:trace($uri as xs:string, $body as item()*, $options as map(xs:string, item())) as map(xs:string, item())

Sends a TRACE request with an optional $body to the supplied $uri and returns the response as a map. Additional $options can be supplied.

http:send

http:send($uri as xs:string, $method as xs:string) as map(xs:string, item())
http:send($uri as xs:string, $method as xs:string, $body as item()*) as map(xs:string, item())
http:send($uri as xs:string, $method as xs:string, $body as item()*, $options as map(xs:string, item())) as map(xs:string, item())

Sends a custom HTTP request with the supplied $method and an optional $body to the specified $uri and returns the response as a map. Additional $options can be supplied. The $method should be given according to the appropriate specification, for HTTP this means in upper-case characters, e.g. GET.

The Request URI

The request URI is always specified in the $uri parameter to each function. The request URI MUST be a valid URI according to the RFC of the HTTP version that is being used for the request. If the URI is invalid, the error http:invalid-uri MUST be raised.

Request Options

The following options can be specified via the $options parameter:

          http:get('http://expath.org/xyz', map {
            'status-only': true(),
            'headers': map { 'User-Agent': 'EXPath/1.0' }
          })
        

Authentication data is processed if a non-empty username is supplied:

          http:delete('http://expath.org/xyz', map {
            'username': 'john',
            'password': '****'
          })
        

The http:invalid-option error will be raised if the value of an option is invalid, or if it has an invalid type.

The Request Entity Body

Some HTTP methods (such as POST, PUT, and others that are less common) transmit an entity body (often colloquially shortened to the "Request Body"). The functions in this module use the $body parameter to supply this.

If the value supplied as the $body parameter is an empty sequence, the corresponding request’s entity body will be omitted.

If the supplied value, or the value(s) of a multipart entity body, have any other type than described in ths section, the http:body error MUST be raised. The http:serialize error MUST be raised if an error occurs whilst serializing an item (e.g. because a supplied map cannot be serialized as JSON).

            http:put('http://expath.org/xyz', 'plain and simple')
          

            http:post(
              'http://expath.org/xyz',
              file:read-text('persons.csv'),
              map { 'headers': 'Content-Type': 'text/csv;charset=UTF-8' }
            )
          

(
  map {
    'headers': map {
      'Content-Disposition': 'form-data; name="file"; filename="covering-letter.md"',
      'Content-Type': 'text/markdown'
    },
    'body': fn:unparsed-text('covering-letter.md')
  },
  map {
    'headers': map {
      'Content-Disposition': 'form-data; name="application-name"'
    },
    'body': 'John Smith'
  },
  map {
    'headers': map {
      'Content-Disposition': 'form-data; name="email"'
    },
    'body': 'john@smith.com'
  }
)
          

          http:send('http://expath.org/xyz', 'POST', (
            (: Body 1, implicit Content-Type: application/xml :)
            map {
              'body': <persons>...</persons>,
            }
            (: Body 2, explicit Content-Type: application/x-object :)
            map {
              'headers': map {
                'Content-Disposition': 'form-data; name="uploadedfile"; filename="hello.o"',
                'Content-Type': 'application/x-object'
              },
              'body': xs:hexBinary('414243')
            }
          ))
        

The Response Map

The HTTP response map contains the following entries. Optional entries are entirely absent from the map if the HTTP response does not contain the corresponding data, for example no body is returned, there will be no body entry.

          map {
            "http-version": "1.1",
            "status": "200",
            "message": "OK",
            "headers": map {
              "Date": "Fri, 31 Dec 1999 23:59:59 GMT",
              "Server": "Apache",
              "Content-Type": "text/plain"
            },
            "body": "Happy new year"
          }
        

The Response Entity Body

HTTP requests sent to the server are under complete the control of the client, as such, the client can carefully dictate the data sent in the request. The opposite is true of the HTTP response returned from the server, over which the client has no control. The majority of the time we can rely on the server to perform as expected and return a meaningful response to our request. However, regardless of whether the server is trusted or not by the user, we cannot rely on it to always operate correctly. Servers can, and often do, return HTTP responses which are not in the spirit of the HTTP request that was made. For example, a server is under no obligation to return data in a format that the client can understand or even read.

The request functions of this module are intentionally biased towards the majority case where the server is responding inline with the requests made to it. This bias takes the form of implicitly parsing the response entity body from the server before it is returned in the response map. This approach eases the job of the developer, by allowing them to work with higher-level XDM type representations of the response body as opposed to the raw HTTP response data.

For those cases where the server is not responding faithfully to the request, or the developer needs a greater level of control over the response, the implicit parsing of the response entity body can be disabled via the parse-response-entity-body request option, see .

          map {
            "status": "200",
            "message": "OK",
            "headers": map {
              "Content-Type": "multipart/mixed"
            },
            "body": [
              map {
                "headers" : map {
                  "Content-Type": "application/json"
                },
                "body": map { "creator": "John", "year": 2018 }
              },
              map {
                "headers" : map {
                  "Content-Type": "image/png"
                },
                "body": xs:base64Binary('abcdefgh')
              }
            ]
          }
        

            (:~
             : Parses a response and returns the parsed body values.
             : @param $response response (top-level, multipart)
             : @return flat sequence with parsed bodies
             :)
            declare function local:parse(
              $response as map(xs:string, item())
            ) as item()* {
              let $type := $response?headers?Content-Type
              let $body := $response?body
              return if(ends-with($type, '/csv') then (
                csv:parse($body)
              ) else if(ends-with($type, '/json') then (
                json:parse($body)
              ) else if(ends-with($type, '/html') then (
                html:parse($body)
              ) else if(starts-with($type, 'multipart/') then (
                (: parse multipart entries recursively :)
                for $part in $body
                return local:parse($part)
              ) else (
                error(xs:QName('http:parse'), 'Type not supported: ' || $type)
              )
            };

            local:parse(
              http:get('http://expath.org/xyz',
                  map { 'parse-response-entity-body': false() })
            )