Skip to content

http\Client

This module provides a simple HTTP Client built on top of java.net.http.HttpClient.

Usage

Function session creates HTTP session context manager. It takes a dictionary with optional settings, such as whether redirects should be followed or an HTTP authentication should be used. This session instance is then used to make HTTP requests.

Example:

with http\Client::session {} as session  # this will create a session without any additional configuration
    (200, headers, body) = http\Client::get session "https://httpbin.org/basic-auth/test/test" {}
end

Another example:

with http\Client::session {:authenticator = (:password, "username", "password"), :follow_redirects = :always} as session # this will initiate a new session, with additional `authenticator` and `follow_redirects` settings
    ...
end

Allowed options

Function http\Client::session accepts a dictionary of options and valid options are:

  • authenticator, which is a triple, currently only password authentication is supported and the triple is of form (:password, "username", "password")
  • follow_redirects, is one of:
    • always: Always redirect
    • never: Never redirect
    • normal: Always redirect, except from HTTPS URLs to HTTP URLs.
  • body_encoding, is either :binary, or :text (default option). When :binary is selected, the body is returned as a sequence of bytes, when :text is selected, the body is returned as a string

Making HTTP requests

This module provides following functions to make HTTP requests:

(status, headers, body) = http\Client::get session "<url>" {}  # where the dictionary can be used to pass HTTP headers
(status, headers, body) = http\Client::delete session "<url>" {}  # where the dictionary can be used to pass HTTP headers
(status, headers, body) = http\Client::post session "<url>" {} []  # where the dictionary can be used to pass HTTP headers, and the last argument is request body (empty string in this case)
(status, headers, body) = http\Client::put session "<url>" {} []  # where the dictionary can be used to pass HTTP headers, and the last argument is request body (empty string in this case)

All these function require a session context manager, url string, a dictionary with HTTP headers and post and put also expect the request body as the last argument. The body can be either a sequence of bytes or a string.

Authorizing a client request

A complete example using HTTP authorization:

with http\Client::session {:authenticator = (:password, "test", "test")} as session
    let
        (200, headers, body) = http\Client::get session "https://httpbin.org/basic-auth/test/test" {}
        {"user" = user, "authenticated" = true} = JSON::parse body
    in
        user
end

which uses httpbin testing service to test HTTP authentication.

Passing HTTP headers in a request

Another example to test request headers, using the same service:

with http\Client::session {} as session
    let
        (200, headers, body) = http\Client::get session "https://httpbin.org/headers" {:accept = "application/json"}
        {"headers" = response_headers} = JSON::parse body
    in
        Dict::lookup response_headers "Accept"
end
Last update: June 20, 2021

Comments