req-api-client

Building API Clients (SDKs) with Req

Overview

Build "Small Development Kits" — minimal, composable API wrappers using Req's plugin architecture instead of massive auto-generated SDKs. The core insight from Dashbit: most apps use 2-3 API calls, not 400 modules.

When to Use

• Building a wrapper around any REST/HTTP API
• Creating a reusable service client (Stripe, S3, GitHub, etc.)
• Integrating with an external service that needs auth, retries, or custom headers
• Adding webhook signature verification

When NOT to use: If a well-maintained Elixir SDK already exists and covers your needs, use it.

Core Pattern: The Module Wrapper

Every API client follows the same new/request/request! shape:

defmodule MyApp.Stripe do
  @doc "Build a configured Req struct. Call with options to override defaults."
  def new(options \\ []) when is_list(options) do
    config = Application.fetch_env!(:my_app, :stripe)

    Req.new(
      base_url: "https://api.stripe.com/v1",
      auth: {:bearer, Keyword.fetch!(config, :api_key)},
      retry: :transient
    )
    |> Req.Request.append_request_steps(
      stripe_post: fn req ->
        # Stripe uses POST for writes — auto-convert GET with body
        with %{method: :get, body: <<_::binary>>} <- req do
          %{req | method: :post}
        end
      end
    )
    |> Req.merge(Keyword.get(config, :req_options, []) ++ options)
  end

  def request(url_or_opts, options \\ [])

  def request(url, options) when is_binary(url),
    do: Req.request(new([url: parse_url(url)] ++ options))

  def request(options, _) when is_list(options),
    do: Req.request(new(options))

  def request!(url_or_opts, options \\ [])

  def request!(url, options) when is_binary(url),
    do: Req.request!(new([url: parse_url(url)] ++ options))

  def request!(options, _) when is_list(options),
    do: Req.request!(new(options))

  # Smart URL routing via pattern matching on resource IDs
  defp parse_url("cus_" <> _ = id), do: "/customers/#{id}"
  defp parse_url("sub_" <> _ = id), do: "/subscriptions/#{id}"
  defp parse_url("/" <> _ = path), do: path
  defp parse_url(path), do: "/" <> path
end