Axial
Repository F# setup
open System
open System.Net.Http
open System.Threading
open System.Threading.Tasks
open Axial
open Axial.HttpClient
open Axial.PlatformService

HTTP Clients

This page shows the shortest path from HttpClient boilerplate to a typed, testable HTTP workflow.

A direct HttpClient call mixes four failure channels into exceptions and manual status checks:

Fragment
// Untracked: exceptions for transport, manual status checks, unchecked parsing.
let! response = client.GetAsync($"https://api.example.com/users/{userId}") |> Async.AwaitTask
response.EnsureSuccessStatusCode() |> ignore
let! body = response.Content.ReadAsStringAsync() |> Async.AwaitTask
let user = parseUser body // throws on bad payloads

The same call as an Axial workflow:

Verified
open Axial.HttpClient
open Axial.HttpClient.DSL

type User = { Id: int; Name: string }

/// A hand-written decoder for {"id":1,"name":"Ada"}; a JSON library's decoder fits the same signature.
let decodeUser (json: string) : Result<User, string> =
    let found = Text.RegularExpressions.Regex.Match(json, """^\{"id":(\d+),"name":"([^"]*)"\}$""")

    if found.Success then Ok { Id = int found.Groups[1].Value; Name = found.Groups[2].Value }
    else Error $"not a user: {json}"

let user (token: string) (userId: int) : Flow<#IHasHttp, HttpError, User> =
    GET $"https://api.example.com/users/{userId}"
    |> bearer token
    |> fetchJson decodeUser

user is a Flow<#IHasHttp, HttpError, User>. The URL hole is URL-encoded as one value, the bearer token is redacted from every plan and error transcript, connection failures, timeouts, unexpected statuses, and decode failures all arrive as one typed HttpError, and nothing is sent until a Flow runtime runs the workflow.

Two Levels

Axial.HttpClient has two deliberate levels:

  1. The Http and Request modules wrap the common HttpClient operations with explicit requests, typed errors, and service-based execution. Use them when you want full control over every request field.
  2. The DSL module adds interpolated URL builders (GET $"..."), pipe-friendly configuration, and terminal verbs (fetch, fetchText, fetchJson) for the everyday call that should read as one line.

Both levels build the same immutable HttpRequest value, so they mix freely: start a request with GET $"..." and finish it with Request.expect [ 200; 404 ] >> Http.sendResult.

Mental Model

  1. Http.get/GET $"..." create an immutable HttpRequest. Construction never performs I/O.
  2. Request.* and DSL combinators (query, bearer, timeout, jsonBody, expect) configure it.
  3. Http.send, fetch, fetchText, or fetchJson convert it to Flow<#IHasHttp, HttpError, _>.
  4. The Flow runtime resolves IHttp from the environment and performs the exchange.

Because the service boundary is one IHttp.Send method, a complete test fake is a few lines, and Request.plan renders a redacted description of any request without sending it.

Choose A Guide

  • Requests: safe interpolated URLs, query parameters, headers, bodies, and secret redaction.
  • Responses and errors: response transcripts, typed JSON decoding, and the HttpError model.
  • Reliability: per-request timeouts, expected statuses, and transient-failure retries.
  • Testing HTTP: fakes, the live HttpClient service, and layer composition.