AI-Optimized Guide: Building Production-Ready REST APIs in Gleam

Technology Stack Overview

Core Components:

• Gleam: Functional language running on BEAM VM (Erlang Virtual Machine)
• Wisp: Web framework with built-in middleware system
• Mist: HTTP server foundation
• Pog: PostgreSQL client with connection pooling
• PostgreSQL: Primary database (SQLite acceptable for prototypes only)

BEAM VM Advantages:

• Handles millions of lightweight processes (not OS threads)
• Built-in fault tolerance with "let it crash" philosophy
• Automatic connection pooling and hot code reloading
• Powers WhatsApp's 2 billion users with 50 engineers
• Trade-off: Slow build times (30-60+ seconds minimum)

Installation and Setup

Environment Setup Requirements

macOS Installation:

brew install gleam

Ubuntu/Debian Installation:

sudo apt-get install erlang-nox
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/

Critical Installation Issues:

• "command not found": PATH configuration problem
• "ERTS not found" or "beam.smp: No such file": Need full Erlang/OTP package, not just runtime
• WSL2 users: Windows PATH conflicts - use export PATH="/usr/local/bin:$PATH" in .bashrc

Project Initialization

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

Package Dependencies:

• gleam_http: HTTP types and utilities
• mist: HTTP server implementation
• wisp: Web framework with middleware and routing
• gleam_json: JSON encoding/decoding
• gleam_erlang: Access to Erlang/OTP features

Version Pinning Strategy: Pin all versions after first successful build to prevent automatic update breakage.

Configuration Management

Secret Key Management

Development (Insecure):

let secret_key_base = wisp.random_string(64)

Production (Secure):

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)
  }
}

Critical Warning: Sessions break when restarting without persistent secret key. Users get logged out unexpectedly.

Environment Configuration

.env File Requirements:

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

Database Integration

PostgreSQL Setup and Connection Pooling

Docker Setup:

docker run --name todo_db \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=todo_api \
  -p 5432:5432 \
  -d postgres

Common Port Conflicts:

• Port 5432 already in use: Kill with sudo lsof -ti:5432 | xargs kill -9
• macOS Postgres.app commonly squats on port 5432
• Alternative: Use different port like -p 5433:5432

Connection Pool Configuration:

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"))
  }
}

Memory Usage Impact:

• BEAM apps: 200MB base memory
• Additional 50MB per 10 connections
• Start with 10 connections, increase when getting "no available connections" errors

Database Schema and Operations

Schema Creation:

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
);

Index Strategy: Don't add indexes initially. Wait for real data to identify slow queries.

Query Implementation:

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
  }
}

Error Handling and Production Failures

Common Production Failures

JSON Decoding Failures:

• Cause: Mobile clients send strings as numbers inconsistently
• iOS: Stringifies everything
• Android: Sometimes sends numbers, sometimes strings
• Solution: Never use assert in production, always pattern match on Result types

Database Connection Failures:

pub fn with_db_retry(db_operation: fn(pog.Connection) -> Result(a, DatabaseError)) -> Result(a, DatabaseError) {
  case db_operation() {
    Ok(result) -> Ok(result)
    Error(DatabaseFailure(_)) as error -> {
      io.println("Database operation failed, retrying...")
      process.sleep(100)
      db_operation()
    }
    Error(other) -> Error(other)
  }
}

PostgreSQL Log Management:

• Critical Issue: PostgreSQL logs can consume entire disk space
• Real Incident: 20GB of query logs caused midnight API failure with "ENOSPC: no space left on device"
• Solution: Implement log rotation immediately

Request Validation and Security

JSON Validation Pattern:

// Wrong - will crash on invalid JSON
let assert Ok(todo) = dynamic.from(json) |> create_todo_decoder()

// Right - handle parsing errors gracefully
case dynamic.from(json) |> create_todo_decoder() {
  Ok(todo) -> handle_valid_todo(todo)
  Error(decode_errors) -> {
    let error_msg = "Invalid JSON: " <> string.inspect(decode_errors)
    wisp.bad_request() |> wisp.json_body(error_response(error_msg))
  }
}

File Upload Security:

pub fn handle_file_upload(req: Request) -> Response {
  use formdata <- wisp.require_multipart_body(req)
  
  case list.key_find(formdata, "file") {
    Ok(wisp.File(filename, content)) -> {
      // Validate file size (max 10MB)
      case bit_array.byte_size(content) > 10_000_000 {
        True -> wisp.request_entity_too_large()
        False -> process_uploaded_file(filename, content)
      }
    }
    _ -> wisp.bad_request() |> wisp.json_body(error_json("No file provided"))
  }
}

Security Requirements:

• Validate file types to prevent executable uploads
• Store files outside web root
• Never use wildcards (*) in CORS origins for production

API Design Patterns

Rate Limiting Implementation

In-Memory Rate Limiter:

pub fn rate_limit_middleware(
  req: Request,
  handle_request: fn(Request) -> Response,
  limit_per_minute: Int,
) -> Response {
  let client_ip = get_client_ip(req)
  let current_minute = get_current_minute()
  let key = client_ip <> ":" <> int.to_string(current_minute)
  
  case get_request_count(key) {
    count if count >= limit_per_minute -> {
      wisp.too_many_requests()
      |> wisp.set_header("retry-after", "60")
      |> wisp.json_body(error_json("Rate limit exceeded"))
    }
    count -> {
      increment_request_count(key)
      handle_request(req)
    }
  }
}

Critical Issue: In-memory rate limiting fails with multiple servers. Use Redis for distributed systems.

CORS Configuration

Development CORS:

fn add_cors_headers(response: Response) -> Response {
  response
  |> wisp.set_header("access-control-allow-origin", "*")
  |> wisp.set_header("access-control-allow-methods", "GET, POST, PUT, DELETE, OPTIONS")
  |> wisp.set_header("access-control-allow-headers", "content-type, authorization")
  |> wisp.set_header("access-control-max-age", "86400")
}

Production Warning: Replace "*" with actual domains. Wildcards defeat CORS security purpose.

API Versioning Strategy

pub fn handle_request(req: Request) -> Response {
  case wisp.path_segments(req) {
    ["api", "v1", ..rest] -> handle_v1_routes(req, rest)
    ["api", "v2", ..rest] -> handle_v2_routes(req, rest)
    _ -> wisp.not_found()
  }
}

Deprecation Policy: Support old versions for minimum one year with documented deprecation dates.

Performance and Monitoring

Performance Characteristics

BEAM/Gleam Trade-offs:

• Strength: Consistent latency under load, handles thousands of concurrent connections
• Weakness: Not optimized for raw per-request throughput
• Use Case: Better for WebSocket servers than high-throughput REST APIs

Common Bottlenecks:

1. Database queries (use indexes and connection pooling)
2. JSON serialization for large objects
3. Memory allocation for temporary objects
4. External API calls without connection pooling

Logging and Monitoring

Structured Logging:

pub fn log_api_request(
  req: Request,
  response_time_ms: Int,
  status_code: Int,
) -> Nil {
  json.object([
    #("timestamp", json.string(get_iso_timestamp())),
    #("method", json.string(http.method_to_string(req.method))),
    #("path", json.string(wisp.path(req))),
    #("status_code", json.int(status_code)),
    #("response_time_ms", json.int(response_time_ms)),
    #("user_agent", json.string(get_user_agent(req))),
  ])
  |> json.to_string
  |> io.println
}

Metrics Endpoint: Add /metrics endpoint for Prometheus or monitoring tool integration.

Framework Comparison Matrix

Feature	Wisp	Mist	Lustre	Cowboy Adapter
Primary Use	REST APIs, web services	Low-level HTTP handling	Browser applications	High-performance HTTP
Learning Difficulty	Easy	Medium	Medium	Hard (requires Erlang knowledge)
Middleware Support	✅ Built-in	❌ Manual	❌ Frontend focus	✅ Via Erlang ecosystem
JSON Handling	✅ Built-in helpers	⚠️ Manual	✅ Frontend data	⚠️ Manual
WebSocket Support	❌ Not built-in	✅ Full API	✅ Frontend WebSockets	✅ Full support
Session Management	✅ Signed cookies	❌ Manual	❌ Frontend only	⚠️ Via Erlang libraries
CORS Support	⚠️ Manual middleware	❌ Manual headers	❌ Browser handles	❌ Manual implementation
Production Maturity	✅ Ready	✅ Battle tested	⚠️ Evolving	✅ Very mature

Resource Requirements and Decision Criteria

Time Investment

• Initial Setup: 2-4 hours for basic API
• Database Integration: 4-8 hours including error handling
• Production Deployment: 8-16 hours with monitoring and security
• Learning Curve: 1-2 weeks for developers familiar with functional programming

Expertise Requirements

• Minimum: Basic functional programming concepts
• Recommended: Erlang/OTP understanding for production debugging
• Critical: PostgreSQL administration for production databases

When to Choose Gleam

• Ideal: High-concurrency applications, WebSocket servers, fault-tolerant systems
• Avoid: High-throughput REST APIs, rapid prototyping, small teams without functional programming experience

Alternative Technologies

• Higher Performance: Go, Rust for raw throughput
• Faster Development: Node.js, Python Flask for rapid prototyping
• Similar Architecture: Elixir/Phoenix for more mature ecosystem

Critical Production Warnings

1. Never use assert in production code - will crash on invalid input
2. Implement log rotation immediately - PostgreSQL logs will fill disk
3. Use connection pooling from start - avoid connection exhaustion
4. Pin dependency versions - automatic updates break builds
5. Validate all file uploads - prevent executable file uploads
6. Use Redis for distributed rate limiting - in-memory fails with multiple servers
7. Set proper CORS origins in production - wildcards defeat security
8. Monitor disk space - database logs grow rapidly
9. Implement proper secret key management - avoid session breakage on restart
10. Test mobile client compatibility - iOS/Android send inconsistent JSON formats