Hcs.Http

hcs · API reference

HTTP request builder DSL.

Use this module to construct client requests with methods, headers, cookies, query parameters, body strings, JSON bodies, and forms before executing them with Client.

HTTP Request Builder DSL.

This module provides a fluent API for building HTTP requests. It's designed to be used with the Client module for a high-level HTTP client experience.

Usage

open Hcs.Http

(* Simple GET request *)
let req = get (Uri.of_string "https://api.example.com/users") |> build

(* POST with JSON body *)
let req =
  post (Uri.of_string "https://api.example.com/users")
  |> content_type "application/json"
  |> body_string {|{"name": "Alice"}|}
  |> build

(* GET with query params and auth *)
let req =
  get (Uri.of_string "https://api.example.com/search")
  |> query "q" "ocaml" |> query "limit" "10" |> bearer "my-token" |> build

Types

type meth = 
  | GET
  | POST
  | PUT
  | DELETE
  | PATCH
  | HEAD
  | OPTIONS
  | CONNECT
  | TRACE
  | Other of string

HTTP method

type body = 
  | Empty
  | String of string
  | Form of (string * string) list

Body content

type builder = {
  meth : meth;
  uri : Uri.t;
  headers : (string * string) list;
  body : body;
}

Request builder - accumulates request parameters

type request = {
  req_meth : meth;
  req_uri : Uri.t;
  req_headers : (string * string) list;
  req_body : body;
}

Built request ready for execution

Method to `Hcs.Method` conversion

Maps the request-builder method to hcs's polymorphic-variant Method.t (the public method type), used by the clients.

val meth_to_h1 : 
  meth ->
  [> `CONNECT
  | `DELETE
  | `GET
  | `HEAD
  | `OPTIONS
  | `Other of string
  | `POST
  | `PUT
  | `TRACE ]

val meth_of_string : string -> meth

val meth_to_string : meth -> string

Request Builders

val create : meth -> Uri.t -> builder

Create a builder with the given method and URI

val get : Uri.t -> builder

Create a GET request builder

val post : Uri.t -> builder

Create a POST request builder

val put : Uri.t -> builder

Create a PUT request builder

val delete : Uri.t -> builder

Create a DELETE request builder

val patch : Uri.t -> builder

Create a PATCH request builder

val head : Uri.t -> builder

Create a HEAD request builder

val options : Uri.t -> builder

Create an OPTIONS request builder

val of_uri : meth -> Uri.t -> builder

Create a request builder from a Uri

Headers

val header : string -> string -> builder -> builder

Add a header to the request

val headers : (string * string) list -> builder -> builder

Add multiple headers to the request

val content_type : string -> builder -> builder

Set the Content-Type header

val accept : string -> builder -> builder

Set the Accept header

val user_agent : string -> builder -> builder

Set the User-Agent header

val bearer : string -> builder -> builder

Set Bearer authentication

val basic_auth : user:string -> pass:string -> builder -> builder

Set Basic authentication

val cookie : string -> string -> builder -> builder

Set a cookie header

val cookies : (string * string) list -> builder -> builder

Set cookies from a list

Query Parameters

val query : string -> string -> builder -> builder

Add a query parameter

val queries : (string * string) list -> builder -> builder

Add multiple query parameters

Body

val body : body -> builder -> builder

Set the request body

val body_string : ?content_type:string -> string -> builder -> builder

Set the body as a string with optional content type

val body_json : string -> builder -> builder

Set the body as a JSON string

val form : (string * string) list -> builder -> builder

Set the body as form data

Building

val build : builder -> request

Build the final request

val url : request -> string

Get the URL as a string

val host : request -> string

Get the host from the request

val port : request -> int

Get the port from the request

val path : request -> string

Get the path from the request

val path_and_query : request -> string

Get the path and query from the request

val is_https : request -> bool

Check if the request is HTTPS

Body Encoding

val encode_form : (string * string) list -> string

Encode form data as URL-encoded string

val body_to_string : body -> string

Get the body as a string

val body_length : body -> int

Get the Content-Length for the body