requests - HTTP Client Library for OCaml #

A modern HTTP(S) client library for OCaml with Eio support, providing a clean API for making web requests with automatic TLS/CA certificate handling. Inspired by Python's requests library.

Key Features #

• Clean Eio-style API: Async I/O using OCaml 5's Eio library
• Automatic TLS: Built-in TLS support with automatic CA certificate handling
• Connection Pooling: Efficient connection reuse via session API
• Authentication: Basic, Bearer, and Digest authentication (RFC 7617, 6750, 7616)
• Cookies: Automatic cookie handling with optional persistence
• Retries: Exponential backoff with jitter
• Timeouts: Configurable connection and read timeouts
• Proxy Support: HTTP/HTTPS proxies with CONNECT tunneling

Installation #

Install with opam:

$ opam install requests

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install requests

Usage #

Session API (Recommended) #

Use sessions for connection pooling, cookie persistence, and shared configuration:

let run () =
  Crypto_rng_unix.use_default ();
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let session = Requests.v ~sw env in
  let response = Requests.get session "https://httpbin.org/get" in
  Printf.printf "Status: %d\n" (Requests.Response.status_code response);
  let body = Requests.Response.text response in
  Printf.printf "Body: %s\n" body

POST with JSON #

let run () =
  Crypto_rng_unix.use_default ();
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let session = Requests.v ~sw env in
  let headers =
    Requests.Headers.(empty |> content_type Requests.Mime.json)
  in
  let body =
    Requests.Body.of_string Requests.Mime.json {|{"key": "value"}|}
  in
  let response =
    Requests.post session ~headers ~body "https://httpbin.org/post"
  in
  Printf.printf "Status: %d\n" (Requests.Response.status_code response)

Authentication #

let run () =
  Crypto_rng_unix.use_default ();
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let session = Requests.v ~sw env in
  (* Basic authentication *)
  let basic = Requests.Auth.basic ~username:"user" ~password:"pass" in
  let r1 =
    Requests.get session ~auth:basic
      "https://httpbin.org/basic-auth/user/pass"
  in
  Printf.printf "Status: %d\n" (Requests.Response.status_code r1);
  (* Bearer token *)
  let bearer = Requests.Auth.bearer ~token:"your-token" in
  let r2 =
    Requests.get session ~auth:bearer
      "https://api.example.com/resource"
  in
  Printf.printf "Status: %d\n" (Requests.Response.status_code r2)

One-Shot API #

For simple, stateless requests without connection pooling:

let run () =
  Crypto_rng_unix.use_default ();
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let response =
    Requests.One.get ~sw
      ~clock:env#clock ~net:env#net
      "https://httpbin.org/get"
  in
  Printf.printf "Status: %d\n" (Requests.Response.status_code response)

Command-Line Tool #

The library includes ocurl, a curl-like command-line tool:

$ # GET request
$ ocurl https://httpbin.org/get

$ # POST with data
$ ocurl -X POST -d '{"key":"value"}' -H "Content-Type: application/json" https://httpbin.org/post

$ # With authentication
$ ocurl -u user:pass https://httpbin.org/basic-auth/user/pass

Documentation #

API documentation is available via:

opam install requests
odig doc requests

Or build locally:

opam exec -- dune build @doc
open _build/default/_doc/_html/index.html

Requirements #

• OCaml 5.1.0+
• Eio library
• TLS support via tls-eio and ca-certs

Licence #

ISC