Overview

Want to Master Pedestal Through Working Code?

This guide teaches you Clojure Pedestal through 80 production-ready code examples rather than lengthy explanations. If you're an experienced developer switching to Pedestal, or want to deepen your framework mastery, you'll build intuition through actual working patterns.

What Is By-Example Learning?

By-example learning is a code-first approach where you learn concepts through annotated, working examples rather than narrative explanations. Each example shows:

1. What the code does - Brief explanation of the Pedestal concept
2. How it works - A focused, heavily commented code example
3. Why it matters - A pattern summary highlighting the key takeaway

This approach works best when you already understand programming fundamentals. You learn Pedestal's idioms, patterns, and best practices by studying real code rather than theoretical descriptions.

What Is Clojure Pedestal?

Pedestal is a web framework for Clojure that centers everything on a single powerful abstraction: the interceptor. Key distinctions:

• Not Ring/Compojure: Pedestal goes beyond Ring middleware stacks with bidirectional interceptor chains that allow error handling in context
• Data-driven: Service configuration is a plain Clojure map, making services composable and testable without starting a real server
• Interceptor-first: Every concern (auth, logging, parsing, routing) becomes an interceptor with enter/leave/error stages
• Immutable context: The request context map flows through the chain, never mutated in place - pure Clojure philosophy
• Multiple transports: HTTP/1.1, HTTP/2, WebSocket, and Server-Sent Events with the same interceptor model

Learning Path

graph TD
  A["Beginner<br/>Core Pedestal Concepts<br/>Examples 1-27"] --> B["Intermediate<br/>Production Patterns<br/>Examples 28-55"]
  B --> C["Advanced<br/>Scale & Resilience<br/>Examples 56-80"]
  D["0%<br/>No Pedestal Knowledge"] -.-> A
  C -.-> E["95%<br/>Framework Mastery"]
 
  style A fill:#0173B2,color:#fff
  style B fill:#DE8F05,color:#fff
  style C fill:#029E73,color:#fff
  style D fill:#CC78BC,color:#fff
  style E fill:#029E73,color:#fff

Coverage Philosophy: 95% Through 80 Examples

The 95% coverage means you'll understand Pedestal deeply enough to build production systems with confidence. It doesn't mean you'll know every edge case or advanced feature - those come with experience.

The 80 examples are organized progressively:

• Beginner (Examples 1-27): Foundation concepts (service map, routing, interceptors, request/response, params, JSON, error handling, logging, configuration)
• Intermediate (Examples 28-55): Production patterns (interceptor chains, custom interceptors, auth, database, SSE, WebSocket, testing, CORS, async, streaming)
• Advanced (Examples 56-80): Scale and resilience (interceptor composition, metrics, tracing, circuit breaker, caching, API versioning, Component/Integrant, Docker, production JVM tuning)

Together, these examples cover 95% of what you'll use in production Pedestal applications.

What's Covered

Core Web Framework Concepts

• Service Map: The central data structure configuring routes, interceptors, host, port, and server type
• Routing: Table routes (explicit, named), terse routes (shorthand), hierarchical routing, HTTP verb dispatch
• Request/Response: The context map (request, response), params, headers, body coercion
• Content Negotiation: Built-in io.pedestal.http.content-negotiation interceptor, Accept header handling

Interceptors

• Interceptor Anatomy: :enter, :leave, :error keys, the context map contract
• Built-in Interceptors: io.pedestal.http.body-params, io.pedestal.http.ring-middlewares, CORS
• Custom Interceptors: Writing pure interceptor maps with interceptor/interceptor
• Interceptor Chains: How Pedestal builds, executes, and short-circuits chains
• Async Interceptors: Returning core.async channels from enter/leave

Data & Persistence

• next.jdbc Integration: Connection pools with HikariCP, query helpers, transaction management
• Connection Pooling: next.jdbc.connection/pool with Pedestal lifecycle
• Migrations: Migratus or Flyway integration patterns
• Query Patterns: jdbc/execute!, jdbc/execute-one!, jdbc/with-transaction

Security & Authentication

• Session-Based Auth: Cookie sessions, login/logout interceptors
• Token Auth: JWT verification interceptor, Authorization header parsing
• Authorization: Role-based interceptors, short-circuit with assoc :response
• CORS: io.pedestal.http.cors built-in support

Testing & Quality

• io.pedestal.test: response-for test helper, testing without a live server
• Unit Testing Interceptors: Testing enter/leave functions in isolation
• Integration Testing: Starting/stopping service in tests with with-server

Production & Operations

• Deployment: Uberjar with lein-uberjar, Docker multi-stage builds
• Configuration: Environment-based config with aero or cprop
• Observability: Metrics with iambrol/pedestal-metrics, structured logging
• JVM Tuning: G1GC flags, heap sizing, container-aware JVM options

What's NOT Covered

We exclude topics that belong in specialized tutorials:

• Detailed Clojure syntax: Master Clojure first through language tutorials
• Advanced DevOps: Kubernetes, service mesh, complex deployment pipelines
• Database internals: Deep PostgreSQL query planning, advanced SQL optimization
• ClojureScript/frontend: Reagent, re-frame, shadow-cljs (frontend-specific tutorials)
• Pedestal internals: How the servlet container integration works at the byte level

For these topics, see dedicated tutorials and framework documentation.

How to Use This Guide

1. Choose Your Starting Point

• New to Pedestal? Start with Beginner (Example 1)
• Framework experience (Ring/Compojure, Spring, Django)? Start with Intermediate (Example 21)
• Building a specific feature? Search for relevant example topic

2. Read the Example

Each example has five parts:

• Explanation (2-3 sentences): What Pedestal concept, why it exists, when to use it
• Diagram (optional): Mermaid diagram for complex flows or data structures
• Code (with heavy comments): Working Clojure code showing the pattern
• Key Takeaway (1-2 sentences): Distilled essence of the pattern
• Why It Matters (50-100 words): Production relevance and real-world impact

3. Run the Code

Create a test project and run each example:

lein new pedestal-service my-app
cd my-app
# Paste example code into src/my_app/service.clj
lein run

4. Modify and Experiment

Change variable names, add interceptors, break things on purpose. Experiment builds intuition faster than reading.

5. Reference as Needed

Use this guide as a reference when building features. Search for relevant examples and adapt patterns to your code.

Relationship to Other Tutorial Types

Prerequisites

Required

• Clojure fundamentals: Basic syntax, sequences, maps, functions, namespaces
• Web development: HTTP basics, REST concepts, JSON
• Programming experience: You've built applications before in another language

Recommended

• Ring knowledge: Understanding Ring's request/response maps helps map concepts
• Leiningen or deps.edn: Build tool familiarity for project management
• Relational databases: SQL basics, schema design for database examples

Not Required

• Pedestal experience: This guide assumes you're new to the framework
• Clojure expertise: Intermediate Clojure knowledge is sufficient
• Erlang/OTP: Pedestal runs on standard JVM, not BEAM

Code Annotation Convention

All code examples use ;; => notation:

(def x 10)               ;; => x is 10 (Long)
(str "hello " "world")   ;; => Returns "hello world" (String)
                          ;; => str concatenates all args as strings
(println x)              ;; => Output: 10

Mermaid diagrams appear when visualizing flow or architecture improves understanding. We use a color-blind friendly palette:

• Blue #0173B2 - Primary
• Orange #DE8F05 - Secondary
• Teal #029E73 - Accent
• Purple #CC78BC - Alternative
• Brown #CA9161 - Neutral

Ready to Start?

Choose your learning path:

• Beginner - Start here if new to Pedestal. Build foundation understanding through 27 core examples.
• Intermediate - Jump here if you know Pedestal basics. Master production patterns through 28 examples.
• Advanced - Expert mastery through 25 advanced examples covering scale, performance, and resilience.

Or jump to specific topics by searching for relevant example keywords (routing, interceptors, authentication, testing, deployment, etc.).

Examples by Level

Beginner (Examples 1–27)

• Example 1: Minimal Pedestal Service
• Example 2: Service Lifecycle with Start and Stop
• Example 3: Development vs Production Service Maps
• Example 4: Table Routes
• Example 5: Terse Routes
• Example 6: Query Parameters and Path Parameters
• Example 7: HTTP Verbs and RESTful Resources
• Example 8: Interceptor Anatomy
• Example 9: The Context Map
• Example 10: Short-Circuiting the Interceptor Chain
• Example 11: Built-in Interceptors
• Example 12: Response Maps
• Example 13: Reading Request Headers
• Example 14: Serving JSON Responses
• Example 15: Content Negotiation
• Example 16: Serving Static Files
• Example 17: Basic Error Handling
• Example 18: Default 404 and Method Not Allowed
• Example 19: Structured Logging with SLF4J
• Example 20: Environment-Based Configuration
• Example 21: Custom Interceptors with interceptor/interceptor
• Example 22: Hierarchical Routes with Common Interceptors
• Example 23: URL Generation with route/url-for
• Example 24: Route Constraints
• Example 25: Router Inspection and Debugging
• Example 26: Helper Functions for Common Responses
• Example 27: Request Validation with clojure.spec

Intermediate (Examples 28–55)

• Example 28: Interceptor Execution Order
• Example 29: Manipulating the Interceptor Queue
• Example 30: Error Propagation Through the Chain
• Example 31: Session-Based Authentication
• Example 32: JWT Token Authentication
• Example 33: Role-Based Authorization
• Example 34: next.jdbc Connection Pool
• Example 35: Basic CRUD with next.jdbc
• Example 36: Database Transactions
• Example 37: Basic Server-Sent Events
• Example 38: SSE with Database Polling
• Example 39: Basic WebSocket Handler
• Example 40: Testing with io.pedestal.test
• Example 41: Testing Interceptors in Isolation
• Example 42: Testing with Mock Dependencies
• Example 43: CORS Configuration
• Example 44: Async Interceptors with core.async
• Example 45: Streaming Large Responses
• Example 46: Multipart File Upload Handling
• Example 47: Database Health Check Interceptor
• Example 48: Custom Content Type Handling
• Example 49: Response Caching Interceptor
• Example 50: Request ID and Correlation
• Example 51: Request Timeout Interceptor
• Example 52: Wrapping Ring Middleware as Interceptors
• Example 53: Form POST Handling
• Example 54: Pagination Pattern
• Example 55: Input Sanitization Interceptor

Advanced (Examples 56–80)

• Example 56: Interceptor Composition with definterceptorfn
• Example 57: Middleware Protocol Pattern
• Example 58: Metrics with Micrometer
• Example 59: Distributed Tracing with OpenTelemetry
• Example 60: Circuit Breaker Pattern
• Example 61: Retry with Exponential Backoff
• Example 62: Application-Level Caching with Caffeine
• Example 63: Distributed Caching with Redis
• Example 64: URL-Based API Versioning
• Example 65: Header-Based API Versioning
• Example 66: Pedestal with Stuart Sierra's Component
• Example 67: Pedestal with Integrant
• Example 68: Uberjar Packaging
• Example 69: Docker Multi-Stage Build
• Example 70: JVM Options for Production
• Example 71: Graceful Shutdown
• Example 72: Property-Based Testing of Interceptors
• Example 73: Load Testing with Gatling
• Example 74: Security Headers Interceptor
• Example 75: SQL Injection Prevention
• Example 76: Route Groups with Versioned Namespaces
• Example 77: Websocket Rooms and Broadcasting
• Example 78: REST API for ClojureScript Frontend
• Example 79: API Response Envelope for Frontend SDKs
• Example 80: Production Deployment Checklist Pattern