Building Web Applications with Servant in Haskell

A Practical Guide to Type-Safe APIs from Design to Deployment

Introduction

Chapter 1: The Haskell Web Ecosystem and Servant’s Philosophy

1. The Landscape of Haskell Web Frameworks
2. What Makes Servant Different
3. Type-Level API Descriptions as Single Source of Truth
4. How Servant Splits Its Responsibilities Across Packages
5. When to Choose Servant and When Not To

Chapter 2: Getting Started with Haskell and Your Development Environment

1. Installing GHC and Choosing a Version
2. Build Tools: Cabal versus Stack in Modern Practice
3. Your First Haskell Project Structure
4. Essential Development Tooling and Extensions
5. Compiling, Running, and Debugging Basics

Chapter 3: The Haskell Foundations You Need for Servant

1. Types, Type Inference, and Algebraic Data Types
2. Functions, Partial Application, and Currying
3. Type Classes: Polymorphism with Structure
4. The Maybe and Either Types for Error Handling
5. Monads: Chaining Computations with Context
6. Monad Transformers: Layering Effects

Chapter 4: Your First Servant API

1. Defining Your First Type-Level API Route
2. The Handler Monad and Returning Responses
3. Serving Your API with Warp
4. Testing Endpoints with curl and HTTP Clients
5. Understanding How Servant Routes Requests to Handlers

Chapter 5: Deep Dive into Servant Combinators

1. HTTP Methods: Get, Post, Put, Patch, Delete
2. Path Parameters with Capture and CaptureAll
3. Query Parameters: Single, Multiple, and Flags
4. Request Bodies with ReqBody
5. Response Types, Status Codes, and Content Types
6. Combining Routes with the Left Alternation Operator

Chapter 6: JSON Serialization with Aeson

1. The Aeson Ecosystem: ToJSON, FromJSON, and Value
2. Manual Instance Derivation for Full Control
3. Automatic Deriving with Generic
4. Custom Serialization Logic
5. Handling Partial Updates and Optional Fields
6. Common JSON Pitfalls in Servant Applications

Chapter 7: API Composition and Modular Design

1. Composing APIs with the Alternation Operator
2. Nested Routes and Sub-APIs
3. Reusable API Type Components
4. Versioning Strategies for Evolving APIs
5. Custom Servant Combinators
6. Module Organization for Large Projects

Chapter 8: Application Environments and Dependency Injection

1. The Problem of Global State in Web Applications
2. ReaderT as an Environment Layer
3. Designing Your Application Environment Record
4. hoistServer: Adapting Handler Monads
5. Configuration Management Across Environments
6. Dependency Injection Patterns in Servant

Chapter 9: Error Handling, Validation, and Logging

1. Servant’s Structured Error System
2. Custom Error Types and Status Codes
3. Input Validation Patterns
4. Logging with Middleware
5. Request IDs and Traceability
6. Exception Handling in Handlers

Chapter 10: Persistence with PostgreSQL

1. Choosing a Database Library: postgresql-simple versus Others
2. Connection Pooling with resource-pool
3. Transactions and Isolation Levels
4. Database Migrations with migrate
5. Repository Layer Design
6. Mapping Between Database and Domain Models

Chapter 11: Authentication and Authorization

1. Security Fundamentals for Web APIs
2. Password Hashing with Argon2 or bcrypt
3. JWT-Based Token Authentication
4. Session and Cookie-Based Authentication
5. Authorization: Roles, Permissions, and Policies
6. Protecting Specific Endpoints with Servant Combinators

Chapter 12: Building the Reference Application

1. Application Architecture Overview
2. Directory Structure and Module Layout
3. Domain Models and Database Schema
4. The Complete API Definition
5. Handler Implementations
6. Configuration and Application Bootstrap

Chapter 13: Clients, Documentation, and External Services

1. Generated Servant Clients
2. Handwritten Client Implementations
3. Calling External APIs from Your Server
4. OpenAPI and Swagger Documentation Generation
5. Serving Interactive API Documentation

Chapter 14: Testing Your Servant Application

1. Unit Testing Handlers in Isolation
2. Property-Based Testing with QuickCheck
3. Integration Tests Against a Running Server
4. Test Databases and Schema Management
5. Mocking External Dependencies
6. Organizing Your Test Suite

Chapter 15: Middleware, CORS, and Cross-Cutting Concerns

1. WAI Middleware Architecture
2. Handling CORS Properly
3. Compression and Performance Middleware
4. Timeouts and Rate Limiting
5. Custom Middleware for Logging and Metrics
6. Ordering and Composing Middleware

Chapter 16: Observability, Performance, and Production Operations

1. Metrics Collection and Monitoring
2. Distributed Tracing Integration
3. Profiling Haskell Web Applications
4. Caching Strategies
5. Concurrency and Resource Limits
6. Graceful Shutdown and Reloading

Chapter 17: Deployment and DevOps

1. Containerizing with Docker
2. Multi-Stage Builds for Small Images
3. Reverse Proxies: Nginx and Traefik
4. HTTPS Termination
5. CI/CD Pipelines with GitHub Actions or GitLab CI
6. Configuration Management in Production

Conclusion: The Servant Way Forward

References

1. Servant Core Documentation and Packages
2. Authentication and Authorization
3. JSON Serialization
4. Web Server and WAI
5. Database Integration
6. OpenAPI and Documentation
7. Testing
8. Build Tools and Tooling
9. GHC and Haskell Language
10. External Articles and Tutorials
11. Academic Papers
12. Version Information Summary