Build API Endpoint Architecture

This chapter establishes a modular, decoupled HTTP routing architecture in Go for retrieving listings from a PostgreSQL database. It contrasts anti-patterns like monolithic inline route handlers and global state with idiomatic Go design patterns, demonstrating how to use higher-order functions and closures to achieve robust dependency injection for database connection pools.

1. The API Endpoint Lifecycle: Request to Database

Building production-grade web APIs requires a clear mental model of how an HTTP request enters the application, passes through the routing layer, accesses the persistence layer, and returns a formatted response.

Client (Insomnia / Browser)
   |
   | HTTP GET http://localhost:8088/listings
   v
Go HTTP Server (net/http ServeMux)
   |
   | Matches route pattern: "GET /listings"
   v
Listing Handler Closure (internal/handlers)
   |
   | Accesses injected *sql.DB pool
   v
PostgreSQL Database (Neon DB Instance)
   |
   | Executes query & retrieves listing rows
   v
Listing Handler
   |
   | Serializes data & writes status code 200
   v
Client receives JSON payload / byte slice

Before writing database queries, the application must establish two foundational capabilities:

1. A deterministic routing mechanism that captures HTTP methods and path patterns.
2. A clean dependency injection pathway to provide the database pool pointer (*sql.DB) to the isolated handler without relying on global state.

2. Diagnosing Route Failures: Network Errors vs. HTTP 404

When developing endpoints test-first using an HTTP client such as Insomnia or Postman, errors provide immediate feedback regarding the current failure state:

Debugging Progression

1. Connection Refusal:

   • Symptom: Insomnia reports Error: Server not responding or connection refused.
   • Cause: The Go binary is not running on port 8088.
   • Remedy: Execute make run to boot the application server.

2. HTTP 404 Not Found:

   • Symptom: The server returns an HTTP 404 Not Found response header.
   • Cause: The server is listening on port 8088, but the internal multiplexer (http.ServeMux) has no handler registered for the path /listings.
   • Remedy: Register the route pattern explicitly in the router.

3. Naive vs. Decoupled Architecture: Moving Beyond Inline Handlers

In rapid prototyping, it is common to define route handlers inline directly inside cmd/api/main.go. However, this approach quickly creates an unmaintainable codebase.

The Naive Approach: Inline Route Handler

// cmd/api/main.go (Anti-Pattern for Monoliths)
package main

import (
	"net/http"
)

func main() {
	mux := http.NewServeMux()

	// Inline handler creates high coupling and pollutes main.go
	mux.HandleFunc("GET /listings", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("all ok"))
	})

	http.ListenAndServe(":8088", mux)
}

Architectural Deficiencies of Inline Handlers

• Separation of Concerns: main.go is responsible for application bootstrap, environment loading, and infrastructure wiring—not HTTP payload validation or business logic.
• Testability: Inline handlers cannot be targeted by package-level unit tests or HTTP integration benchmarks without booting the entire server.
• Maintainability: As query parameters, authorization headers, and database interactions are added, main.go expands into an unwieldy file.

The Decoupled Approach: Package-Level Separation

To enforce modular boundaries, handlers belong inside a dedicated package under the internal/ directory tree (e.g., internal/handlers/listings.go).

4. Database State & Mock Data: Neon PostgreSQL Seeding

Querying data requires populated records in the persistence layer. In a serverless PostgreSQL environment such as Neon, mock records can be applied through seed scripts.

Mock Seed Script (seeds/listings.sql)

-- Seed script for listings table
INSERT INTO listings (
    title,
    description,
    price_per_night,
    location,
    created_at,
    updated_at
) VALUES 
(
    'Modern Coastal Villa',
    'A serene 3-bedroom villa overlooking the ocean with a private pool.',
    250.00,
    'Malibu, California',
    NOW(),
    NOW()
),
(
    'Downtown Loft Apartment',
    'Centrally located loft apartment within walking distance of prime restaurants.',
    120.00,
    'Seattle, Washington',
    NOW(),
    NOW()
);

Verification Flow

Applying this script guarantees that when the Go application queries the database, the cursor reads valid database rows instead of throwing sql.ErrNoRows or returning empty result sets.

5. The Dependency Injection Problem in Go HTTP Handlers

Once the seed data exists and the handler is isolated in internal/handlers/listings.go, the handler must execute queries against PostgreSQL. This requires an active connection pool (*sql.DB).

The Global State Anti-Pattern (Common in Node.js/JavaScript)

In some programming environments, developers instantiate a database client in a separate module and import it globally:

In Go, importing a global database variable introduces major drawbacks:

1. Hidden Dependencies: Inspecting the handler’s function signature does not reveal that it communicates with a database.
2. Concurrent Test Collisions: Parallel unit tests modifying or mocking a global database variable encounter race conditions.
3. Inability to Swap Drivers: You cannot easily swap the production database pool with an in-memory SQL mock or transaction wrapper during automated testing.

Idiomatic Solution: Explicit Dependency Injection

In idiomatic Go, dependencies must be passed down explicitly through call stacks. A function or handler should explicitly state what it needs to execute its duties.

6. Architectural Solution: Closures as Handler Factories

Standard Go HTTP handlers conform strictly to the http.HandlerFunc signature:

type HandlerFunc func(http.ResponseWriter, *http.Request)

Because the router (http.ServeMux) only passes http.ResponseWriter and *http.Request to the handler, an extra argument like *sql.DB cannot be added directly to the signature.

The Closure (Factory Function) Mechanism

To inject *sql.DB, we wrap the actual HTTP handler inside an outer constructor function (a factory). The outer function takes the dependency as an argument and returns the http.HandlerFunc.

Mental Hook: The Factory Analogy

Factory Analogy: Think of the outer function (List(db)) as a customized machine assembler. You provide the raw tool (*sql.DB) to the factory once during startup. The factory uses that tool to build an operational worker (http.HandlerFunc) with the tool locked inside its workstation. Every time a customer arrives (an incoming HTTP request), that dedicated worker processes the task using the pre-configured tool.

7. Step-by-Step Code Evolution

Step 1: Initial Handler Definition (Without Dependencies)

Initially, the handler is extracted from main.go into internal/handlers/listings.go:

// internal/handlers/listings.go
package handlers

import (
	"net/http"
)

// List handles HTTP GET requests to fetch listings
func List(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("all ok"))
}

At this stage, List matches http.HandlerFunc, but it has no mechanism to access the database.

Step 2: Refactoring List into a Higher-Order Function

Transform List into a closure factory that accepts *sql.DB and returns an http.HandlerFunc:

// internal/handlers/listings.go
package handlers

import (
	"database/sql"
	"net/http"
)

// List returns an http.HandlerFunc that has access to the *sql.DB connection pool
// through lexical scoping (closure).
func List(db *sql.DB) http.HandlerFunc {
	// Any setup logic for the handler runs once here during server bootstrap

	return func(w http.ResponseWriter, r *http.Request) {
		// This inner function executes for every incoming HTTP request.
		// 'db' is captured from the outer scope.
		
		// Placeholder verification response before adding SQL querying logic
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("all ok"))
	}
}

Note: The return type must explicitly be http.HandlerFunc. Returning an anonymous function with matching parameter types without specifying http.HandlerFunc can cause compile-time type errors when registered with specific routing multiplexers.

Step 3: Wiring Dependencies in cmd/api/main.go

In cmd/api/main.go, instantiate the database pool, unwrap the variable (changing _ = db to db), and pass it directly to handlers.List(db):

// cmd/api/main.go
package main

import (
	"log"
	"net/http"

	"github.com/example/monolith/internal/database"
	"github.com/example/monolith/internal/handlers"
)

func main() {
	// 1. Establish database connection pool
	db, err := database.Connect()
	if err != nil {
		log.Fatalf("Failed to initialize database pool: %v", err)
	}
	defer db.Close()

	// 2. Initialize router
	mux := http.NewServeMux()

	// 3. Register route using the closure factory
	// handlers.List(db) executes immediately, returning the closure with db enclosed.
	mux.HandleFunc("GET /listings", handlers.List(db))

	// 4. Start HTTP Server
	log.Println("Server running on port :8088")
	if err := http.ListenAndServe(":8088", mux); err != nil {
		log.Fatalf("Server failed to start: %v", err)
	}
}

8. Summary of Routing & Injection Mechanics

The following comparison details how different architectural configurations handle dependencies and request execution:

9. Summary and Key Takeaways

• Clear Boundary Isolation: Placing HTTP handlers in cmd/api/main.go creates tech debt. Encapsulate business logic within dedicated domain packages inside the internal/ directory tree (e.g., internal/handlers).
• Method-Specific Routing: Modern Go (Go 1.22+) supports method routing directly in the multiplexer patterns (e.g., mux.HandleFunc("GET /listings", ...)), eliminating manual r.Method checks inside handlers.
• Fail Early with Verification Tools: Using tools like Insomnia during each refactoring step helps immediately distinguish infrastructure failures (server down, socket connection refused) from routing errors (HTTP 404 Not Found).
• Avoid Global State: Do not rely on package-level global variables for stateful resources like *sql.DB. Global state obscures dependencies, introduces race conditions during automated testing, and harms maintainability.
• Closure-Based Dependency Injection: Because http.HandlerFunc accepts only http.ResponseWriter and *http.Request, use a factory function (func List(db *sql.DB) http.HandlerFunc) to inject database connections and services via lexical closures.
• Controlled Execution Timing: The outer factory runs once during application startup when wiring the router; the returned inner closure executes on every inbound HTTP request, retaining access to the enclosed dependencies throughout the application lifecycle.