Build REST APIs in Gleam That Don't Crash in Production

Install Gleam Without Getting Fucked by Dependencies

First things first - get Gleam and Erlang installed. Gleam runs on the BEAM VM (same as WhatsApp's backend), so you need Erlang first.

macOS (the easy way):

brew install gleam

Ubuntu/Debian (the annoying way):

sudo apt-get install erlang-nox
## Check latest release first, I'm using v1.3.2 but grab whatever's newest
## Official releases: https://github.com/gleam-lang/gleam/releases
## Installation guide: https://gleam.run/getting-started/installing/
wget https://github.com/gleam-lang/gleam/releases/download/v1.3.2/gleam-v1.3.2-x86_64-unknown-linux-musl.tar.gz
tar -xzf gleam-v1.3.2-x86_64-unknown-linux-musl.tar.gz
sudo mv gleam /usr/local/bin/

Make sure it works:

gleam --version
## Should show v1.3.2 or whatever version you downloaded

If you get "command not found", check your PATH. If you get weird Erlang errors like "ERTS not found" or "beam.smp: No such file", you probably need to install the full Erlang/OTP package, not just the runtime. Ubuntu's erlang-nox is the minimal one that actually works. WSL2 users: the Windows PATH fucks with everything - use export PATH="/usr/local/bin:$PATH" in your .bashrc. More troubleshooting tips here.

Create a New Project That Actually Works

gleam new todo_api
cd todo_api
gleam add mist wisp gleam_http gleam_json gleam_erlang

Don't pin versions unless something breaks. Latest Gleam with these packages works fine. I once had our build break because of an automatic update to gleam_json - now I pin everything. Here's what you just installed:

• gleam_http: HTTP types so you don't have to write them
• mist: The HTTP server that doesn't suck
• wisp: Web framework with middleware and cookies
• gleam_json: JSON handling without wanting to die
• gleam_erlang: Access to Erlang/OTP goodies

Check the Gleam package index for the latest versions and Hex docs for API documentation.

Why BEAM Matters (And Why Your Node.js Backend is Slow)

Gleam runs on BEAM - the same virtual machine powering WhatsApp's 2 billion users. While you're manually managing connection pools in Express, BEAM gives you:

• Lightweight processes - millions of them, not OS threads that eat RAM (Erlang processes vs threads)
• Fault tolerance - one broken request won't kill your server (Let it crash philosophy)
• Built-in connection pooling - no more "connection limit exceeded" errors
• Hot code reloading - deploy without downtime (Code reloading docs)

The catch? Gleam builds are slow as hell. Budget 30-60 seconds minimum, sometimes way longer if the build gods hate you that day. See performance tips for optimization strategies.

Build Your First HTTP Server

Replace src/todo_api.gleam with this:

import gleam/erlang/process
import mist
import wisp
import wisp/wisp_mist

pub fn main() {
  wisp.configure_logger()
  
  // Generate random secret - you'll need a real one in production
  let secret_key_base = wisp.random_string(64)
  
  let assert Ok(_) =
    wisp_mist.handler(handle_request, secret_key_base)
    |> mist.new
    |> mist.port(8000)
    |> mist.start_http
  
  process.sleep_forever()
}

fn handle_request(req: wisp.Request) -> wisp.Response {
  case wisp.path_segments(req) {
    [] -> wisp.ok() |> wisp.html_body("<h1>Todo API is running</h1>")
    ["api", "v1", "todos"] -> handle_todos(req)
    _ -> wisp.not_found()
  }
}

fn handle_todos(req: wisp.Request) -> wisp.Response {
  case req.method {
    Get -> {
      let json = "{\"todos\": [{\"id\": \"1\", \"title\": \"Learn Gleam\", \"completed\": false}]}"
      wisp.ok()
      |> wisp.set_header("content-type", "application/json")
      |> wisp.html_body(json)
    }
    _ -> wisp.method_not_allowed([Get])
  }
}

Start it up:

gleam run

Visit http://localhost:8000 in your browser to see it working. Hit /api/v1/todos for your first JSON response. Check the Wisp documentation for more routing patterns and the Mist server guide for configuration options.

The Secret Key Gotcha That'll Ruin Your Weekend

Don't forget the secret_key_base in production. Took me way too long to figure out that sessions break when you restart without a persistent secret key. Users kept getting logged out. Oops. Read more about session management in Wisp and security best practices.

In production, load it from environment:

let secret_key = case gleam/os.get_env("SECRET_KEY_BASE") {
  Ok(key) if string.length(key) >= 64 -> key
  Ok(short_key) -> {
    io.println("ERROR: SECRET_KEY_BASE too short, need 64+ chars")
    process.halt(1)
  }
  Error(_) -> {
    io.println("WARNING: Using insecure random key, set SECRET_KEY_BASE") 
    wisp.random_string(64)
  }
}

JSON Handling That Won't Make You Want to Quit

Create src/app/models/todo.gleam:

import gleam/json
import gleam/dynamic

pub type Todo {
  Todo(id: String, title: String, completed: Bool)
}

pub fn todo_to_json(todo: Todo) -> json.Json {
  json.object([
    #("id", json.string(todo.id)),
    #("title", json.string(todo.title)),
    #("completed", json.bool(todo.completed)),
  ])
}

pub fn create_todo_decoder() -> dynamic.Decoder(Todo) {
  dynamic.decode3(
    Todo,
    dynamic.field("id", dynamic.string),
    dynamic.field("title", dynamic.string),
    dynamic.field("completed", dynamic.bool),
  )
}

Testing Your API (And Why It'll Probably Break)

Test your API locally once it's running - you'll hit the usual issues like CORS errors from browsers and JSON decode failures when mobile clients send strings as numbers.

Common issues you'll hit:

• CORS errors: "Access blocked by CORS policy" - browsers hate you by default
• JSON decode failures: Mobile clients love sending strings as numbers
• Connection refused: "ECONNREFUSED 127.0.0.1:8000" - server crashed, check the logs
• 500 errors: "Internal Server Error" - something fucked up in your code

The decoder gives you garbage error messages like "decode error at $.id: expected int, found string". Mobile apps love sending {"id": "123"} when you expect {"id": 123}. You'll spend way too long figuring out string vs number bullshit until you add proper error handling. iOS stringifies everything, Android sometimes sends actual numbers, sometimes doesn't. It's a shitshow.

Check out the JSON decoding guide for better error handling patterns and the mobile API best practices for dealing with inconsistent client behavior.

Get PostgreSQL Running

You need a real database. SQLite is fine for prototyping, but PostgreSQL won't randomly corrupt your data. See database comparison guide for other options.

gleam add pog envoy

pog is the PostgreSQL client that doesn't suck. envoy reads environment variables without making you want to quit. Check the database connectivity guide for connection patterns.

Spin Up PostgreSQL (Docker is Easiest)

## Start PostgreSQL in Docker - memorize this command
docker run --name todo_db \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=todo_api \
  -p 5432:5432 \
  -d postgres

If Docker gives you "port already in use", something else is using port 5432. Kill it with sudo lsof -ti:5432 | xargs kill -9 or use a different port like -p 5433:5432. On macOS, Postgres.app loves to squat on 5432. See Docker networking guide for port management tips.

Create your .env file:

DATABASE_URL=postgresql://postgres:password@localhost:5432/todo_api
SECRET_KEY_BASE=generate_a_real_64_character_secret_here

Database Connection Pool Hell

Create src/app/database.gleam:

import envoy
import pog
import gleam/result

pub type DatabaseError {
  ConfigError(String)
  ConnectionFailed(String)
}

pub fn get_db_config() -> Result(String, DatabaseError) {
  case envoy.get(\"DATABASE_URL\") {
    Ok(url) -> Ok(url)
    Error(_) -> Error(ConfigError(\"DATABASE_URL not set. Check your .env file.\"))
  }
}

pub fn create_pool(pool_size: Int) -> Result(pog.Config, DatabaseError) {
  use db_url <- result.try(get_db_config())
  
  case pog.url_config(db_url) {
    Ok(config) -> 
      Ok(config |> pog.pool_size(pool_size) |> pog.default_timeout(5000))
    Error(_) -> 
      Error(ConfigError(\"Invalid DATABASE_URL format\"))
  }
}

Connection pools work until they don't. Start with 10 connections or whatever seems reasonable. Bump it up when you start getting "no available connections" errors. BEAM apps eat 200MB base memory, plus another 50MB per 10 connections. Found this out when our monitoring started alerting at 4am. Read more about connection pool tuning and BEAM memory management.

Create the Database Schema

Create schema.sql:

CREATE TABLE todos (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  completed BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Apply it:

## With Docker (mount the schema file or copy-paste)
docker exec -i todo_db psql -U postgres -d todo_api < schema.sql

## Local PostgreSQL
psql -d todo_api -f schema.sql

## If you get \"relation already exists\" - you ran it twice, ignore it

Don't add indexes yet. You don't know which queries will be slow until you have real data. Check PostgreSQL performance tips and the indexing guide when you have production data.

Wire Up Database Operations

Update your Todo model to work with the database. Create src/app/models/todo.gleam:

import gleam/json
import gleam/dynamic
import pog

pub type Todo {
  Todo(id: String, title: String, completed: Bool, created_at: String)
}

pub fn todo_decoder() -> dynamic.Decoder(Todo) {
  dynamic.decode4(
    Todo,
    dynamic.field(\"id\", dynamic.string),
    dynamic.field(\"title\", dynamic.string),
    dynamic.field(\"completed\", dynamic.bool),
    dynamic.field(\"created_at\", dynamic.string),
  )
}

pub fn todo_to_json(todo: Todo) -> json.Json {
  json.object([
    #(\"id\", json.string(todo.id)),
    #(\"title\", json.string(todo.title)),
    #(\"completed\", json.bool(todo.completed)),
    #(\"created_at\", json.string(todo.created_at)),
  ])
}

Basic Database Queries That Work

Create src/app/db.gleam for database operations:

import pog
import gleam/result
import gleam/list
import app/models/todo.{Todo}

pub fn list_todos(db: pog.Connection) -> List(Todo) {
  let sql = \"SELECT id, title, completed, created_at FROM todos ORDER BY created_at DESC\"
  
  case pog.query(sql) |> pog.returning(todo.todo_decoder()) |> pog.execute(db) {
    Ok(response) -> response.rows
    Error(_) -> []  // Return empty list on error
  }
}

pub fn create_todo(db: pog.Connection, title: String) -> Result(Todo, String) {
  let sql = \"INSERT INTO todos (title) VALUES ($1) RETURNING id, title, completed, created_at\"
  
  case pog.query(sql)
    |> pog.parameter(pog.text(title))
    |> pog.returning(todo.todo_decoder())
    |> pog.execute(db) {
    Ok(response) -> 
      case response.rows {
        [new_todo] -> Ok(new_todo)
        _ -> Error(\"Failed to create todo\")
      }
    Error(_) -> Error(\"Database error\")
  }
}

Test It Out

Update your main handler to use the database:

fn handle_todos(req: wisp.Request, db: pog.Connection) -> wisp.Response {
  case req.method {
    Get -> {
      let todos = db.list_todos(db)
      let json = todos
        |> list.map(todo.todo_to_json)
        |> json.array
        |> json.to_string_builder
      
      wisp.ok()
      |> wisp.set_header(\"content-type\", \"application/json\")
      |> wisp.set_body(json)
    }
    _ -> wisp.method_not_allowed([Get])
  }
}

Now you can:

## Start with database
DATABASE_URL=postgresql://postgres:password@localhost:5432/todo_api gleam run

## Create and list todos
curl -X POST localhost:8000/api/v1/todos -H \"Content-Type: application/json\" -d '{\"title\": \"Test\"}'
curl localhost:8000/api/v1/todos

Common database errors you'll hit:

• Connection refused: PostgreSQL isn't running
• Authentication failed: Wrong username/password in DATABASE_URL
• Relation does not exist: You forgot to run the schema
• Connection pool exhausted: Too many concurrent requests

PostgreSQL logs will slowly eat your disk space. Set up log rotation or prepare for midnight panic when disk space hits zero. Learned this the hard way when our API died in the middle of the night because PostgreSQL filled up our disk - I think it was like 20GB of query logs. The error was just "ENOSPC: no space left on device" - super helpful.

Set up log rotation and monitoring early. Use pgTune for basic configuration optimization and PostgreSQL monitoring tools for production setups.