Building Production Ready REST APIs in Go: The Complete Gold Standard Guide

Table of Contents

1. The Anatomy of a Production API
2. Project Structure That Scales
3. HTTP Methods: When and Why
4. HTTP Status Codes: Speaking the Right Language
5. Routing Done Right
6. Middleware: The Unsung Heroes
7. Request Validation: Trust Nobody
8. Error Handling: Failing Gracefully
9. Authentication: Who Are You?
10. Authorization: What Can You Do?
11. Database Patterns for APIs
12. Caching Strategies
13. Rate Limiting: Protecting Your Service
14. Logging: Your Production Lifeline
15. Monitoring and Observability
16. HATEOAS: Self Documenting APIs
17. API Versioning
18. Testing Production APIs
19. Deployment Considerations
20. Complete Working Example

The Anatomy of a Production API

💡 Think of it like this: A production API is like a well run hospital emergency room. Patients (requests) arrive constantly, some critical, some routine. There's a triage system (load balancer), specialized doctors (handlers), medical records (database), security (authentication), visiting hours policy (rate limiting), and detailed charts (logging). Everything works together, and if one system fails, others compensate.

What Makes an API "Production Ready"?

REST API architecture diagram 1

Project Structure That Scales

The Gold Standard: Domain Driven Structure

myapi/
├── cmd/
│   └── api/
│       └── main.go                 # Application entry point
├── internal/
│   ├── config/
│   │   └── config.go               # Configuration management
│   ├── domain/
│   │   ├── user/
│   │   │   ├── entity.go           # User domain entity
│   │   │   ├── repository.go       # Repository interface
│   │   │   └── service.go          # Business logic
│   │   └── order/
│   │       ├── entity.go
│   │       ├── repository.go
│   │       └── service.go
│   ├── handler/
│   │   ├── user_handler.go         # HTTP handlers for users
│   │   ├── order_handler.go
│   │   └── health_handler.go
│   ├── middleware/
│   │   ├── auth.go                 # Authentication middleware
│   │   ├── logging.go              # Request logging
│   │   ├── ratelimit.go            # Rate limiting
│   │   ├── recovery.go             # Panic recovery
│   │   └── cors.go                 # CORS handling
│   ├── repository/
│   │   ├── postgres/
│   │   │   ├── user_repo.go        # PostgreSQL implementation
│   │   │   └── order_repo.go
│   │   └── redis/
│   │       └── cache.go            # Redis cache implementation
│   ├── router/
│   │   └── router.go               # Route definitions
│   └── pkg/
│       ├── validator/
│       │   └── validator.go        # Request validation
│       ├── response/
│       │   └── response.go         # Standardized responses
│       ├── errors/
│       │   └── errors.go           # Custom error types
│       └── logger/
│           └── logger.go           # Structured logging
├── migrations/
│   ├── 001_create_users.up.sql
│   └── 001_create_users.down.sql
├── api/
│   └── openapi.yaml                # API specification
├── scripts/
│   └── setup.sh                    # Development scripts
├── Dockerfile
├── docker-compose.yml
├── Makefile
├── go.mod
└── go.sum

Why This Structure?

• entity.go: Pure data structures, no dependencies
• repository.go: Interface defining data access contracts
• service.go: Business logic, depends on repository interface (not implementation)

GoGoGo
// Filename: internal/domain/user/entity.go
package user

import (
    "time"
)

// User represents a user in our system
// Why: This is a pure domain entity with no external dependencies.
// It represents the core business concept of a "user" and can be used
// across all layers without importing HTTP or database packages.
type User struct {
    ID        string    `json:"id"`
    Email     string    `json:"email"`
    Name      string    `json:"name"`
    Role      Role      `json:"role"`
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}

// Role represents user roles in the system
// Why: Using a custom type instead of string provides type safety
// and prevents invalid role assignments at compile time.
type Role string

const (
    RoleAdmin  Role = "admin"
    RoleUser   Role = "user"
    RoleGuest  Role = "guest"
)

// IsValid checks if the role is a valid system role
// Why: Validation at the domain level ensures business rules
// are enforced regardless of how the data enters the system.
func (r Role) IsValid() bool {
    switch r {
    case RoleAdmin, RoleUser, RoleGuest:
        return true
    default:
        return false
    }
}

HTTP Methods: When and Why

REST API architecture diagram 2

The Complete HTTP Methods Guide

Understanding Idempotency

💡 Think of it like this: Pressing an elevator button once or ten times has the same effect. The elevator comes. That's idempotency. But putting a letter in a mailbox is not idempotent. Each letter you put in is a new letter.

• Retry logic (network failures)
• Caching
• Distributed systems

go
// Filename: internal/handler/user_handler.go
package handler

import (
    "encoding/json"
    "net/http"

    "myapi/internal/domain/user"
    "myapi/internal/pkg/response"
)

type UserHandler struct {
    service *user.Service
}

func NewUserHandler(service *user.Service) *UserHandler {
    return &UserHandler{service: service}
}

// GET /users/{id}
// Why GET: We're retrieving data without modifying anything.
// GET is safe (no side effects) and cacheable.
func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
    // Why: Extract ID from URL path
    id := r.PathValue("id") // Go 1.22+ built-in routing

    user, err := h.service.GetUser(r.Context(), id)
    if err != nil {
        response.Error(w, http.StatusNotFound, "User not found")
        return
    }

    response.JSON(w, http.StatusOK, user)
}

// POST /users
// Why POST: We're creating a new resource. Each request creates
// a new user, so it's not idempotent. POST is the correct choice.
func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        response.Error(w, http.StatusBadRequest, "Invalid request body")
        return
    }

    // Why: Service layer handles business logic
    user, err := h.service.CreateUser(
        r.Context(),
        req.Email,
        req.Name,
        user.Role(req.Role),
    )
    if err != nil {
        response.Error(w, http.StatusBadRequest, err.Error())
        return
    }

    // Why 201: Resource was created. Include Location header
    // pointing to the new resource.
    w.Header().Set("Location", "/users/"+user.ID)
    response.JSON(w, http.StatusCreated, user)
}

// PUT /users/{id}
// Why PUT: We're replacing the entire resource. PUT is idempotent.
// Making the same PUT request multiple times results in the same state.
func (h *UserHandler) ReplaceUser(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    var req ReplaceUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        response.Error(w, http.StatusBadRequest, "Invalid request body")
        return
    }

    // Why: PUT replaces the entire resource, so all fields are required
    user, err := h.service.ReplaceUser(r.Context(), id, req.Email, req.Name, user.Role(req.Role))
    if err != nil {
        response.Error(w, http.StatusBadRequest, err.Error())
        return
    }

    response.JSON(w, http.StatusOK, user)
}

// PATCH /users/{id}
// Why PATCH: We're making a partial update. Only the fields
// provided in the request will be updated.
func (h *UserHandler) UpdateUser(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    var req UpdateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        response.Error(w, http.StatusBadRequest, "Invalid request body")
        return
    }

    // Why: PATCH allows partial updates
    user, err := h.service.UpdateUser(r.Context(), id, req.Name, user.Role(req.Role))
    if err != nil {
        response.Error(w, http.StatusBadRequest, err.Error())
        return
    }

    response.JSON(w, http.StatusOK, user)
}

// DELETE /users/{id}
// Why DELETE: We're removing a resource. DELETE is idempotent.
// Deleting the same resource twice results in the same state (deleted).
func (h *UserHandler) DeleteUser(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    if err := h.service.DeleteUser(r.Context(), id); err != nil {
        response.Error(w, http.StatusNotFound, "User not found")
        return
    }

    // Why 204: Successful deletion with no content to return
    w.WriteHeader(http.StatusNoContent)
}

// Request DTOs
type CreateUserRequest struct {
    Email string `json:"email"`
    Name  string `json:"name"`
    Role  string `json:"role"`
}

type ReplaceUserRequest struct {
    Email string `json:"email"`
    Name  string `json:"name"`
    Role  string `json:"role"`
}

type UpdateUserRequest struct {
    Name string `json:"name,omitempty"`
    Role string `json:"role,omitempty"`
}

PUT vs PATCH: The Critical Difference

json
PUT /users/123
{
    "email": "new@example.com",
    "name": "New Name",
    "role": "admin"
}

json
PATCH /users/123
{
    "name": "New Name"
}

When to Use POST for Actions

POST /users/123/suspend      # Suspend a user
POST /orders/456/cancel      # Cancel an order
POST /payments/process       # Process payment
POST /reports/generate       # Generate a report

• They're not idempotent (suspending twice might have different effects)
• They don't map cleanly to resource creation/modification
• They often trigger side effects (emails, notifications)

HTTP Status Codes: Speaking the Right Language

REST API architecture diagram 3

The Complete Status Code Guide for APIs

Success Codes (2xx)

Client Error Codes (4xx)

Server Error Codes (5xx)

400 vs 422: The Subtle Difference

• Malformed JSON
• Missing required headers
• Invalid content type

• Email format is invalid
• Password too short
• Date in the past when future required

go
// Filename: internal/pkg/response/response.go
package response

import (
    "encoding/json"
    "net/http"
)

// APIResponse is the standard response wrapper
// Why: Consistent response format makes client implementation easier
// and allows for metadata like pagination info.
type APIResponse struct {
    Success bool        `json:"success"`
    Data    interface{} `json:"data,omitempty"`
    Error   *APIError   `json:"error,omitempty"`
    Meta    *Meta       `json:"meta,omitempty"`
}

// APIError represents an error response
// Why: Structured errors allow clients to handle errors programmatically
type APIError struct {
    Code    string            `json:"code"`              // Machine-readable code
    Message string            `json:"message"`           // Human-readable message
    Details map[string]string `json:"details,omitempty"` // Field-level errors
}

// Meta contains response metadata
type Meta struct {
    Page       int `json:"page,omitempty"`
    PageSize   int `json:"page_size,omitempty"`
    TotalItems int `json:"total_items,omitempty"`
    TotalPages int `json:"total_pages,omitempty"`
}

// JSON sends a successful JSON response
// Why: Centralizing response handling ensures consistent Content-Type
// headers and JSON encoding across all handlers.
func JSON(w http.ResponseWriter, status int, data interface{}) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)

    resp := APIResponse{
        Success: true,
        Data:    data,
    }

    json.NewEncoder(w).Encode(resp)
}

// JSONWithMeta sends a JSON response with metadata
// Why: Useful for paginated responses
func JSONWithMeta(w http.ResponseWriter, status int, data interface{}, meta *Meta) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)

    resp := APIResponse{
        Success: true,
        Data:    data,
        Meta:    meta,
    }

    json.NewEncoder(w).Encode(resp)
}

// Error sends an error response
// Why: Consistent error format helps clients handle errors uniformly
func Error(w http.ResponseWriter, status int, message string) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)

    resp := APIResponse{
        Success: false,
        Error: &APIError{
            Code:    httpStatusToCode(status),
            Message: message,
        },
    }

    json.NewEncoder(w).Encode(resp)
}

// ValidationError sends a 422 with field-level errors
// Why: Helps clients display errors next to form fields
func ValidationError(w http.ResponseWriter, errors map[string]string) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusUnprocessableEntity)

    resp := APIResponse{
        Success: false,
        Error: &APIError{
            Code:    "VALIDATION_ERROR",
            Message: "Validation failed",
            Details: errors,
        },
    }

    json.NewEncoder(w).Encode(resp)
}

// httpStatusToCode converts HTTP status to error code
// Why: Machine-readable codes are easier to handle than status numbers
func httpStatusToCode(status int) string {
    codes := map[int]string{
        400: "BAD_REQUEST",
        401: "UNAUTHORIZED",
        403: "FORBIDDEN",
        404: "NOT_FOUND",
        409: "CONFLICT",
        422: "VALIDATION_ERROR",
        429: "RATE_LIMITED",
        500: "INTERNAL_ERROR",
        502: "BAD_GATEWAY",
        503: "SERVICE_UNAVAILABLE",
    }

    if code, ok := codes[status]; ok {
        return code
    }
    return "UNKNOWN_ERROR"
}

json
{
    "success": true,
    "data": {
        "id": "123",
        "email": "user@example.com",
        "name": "John Doe",
        "role": "user"
    }
}

json
{
    "success": true,
    "data": [
        {"id": "1", "name": "User 1"},
        {"id": "2", "name": "User 2"}
    ],
    "meta": {
        "page": 1,
        "page_size": 10,
        "total_items": 100,
        "total_pages": 10
    }
}

json
{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Validation failed",
        "details": {
            "email": "Invalid email format",
            "password": "Must be at least 8 characters"
        }
    }
}

Routing Done Right

RESTful URL Design Principles

REST API architecture diagram 4

URL Design Rules

✅ GET  /users          (get all users)
✅ POST /users          (create user)
❌ GET  /getUsers
❌ POST /createUser

✅ /users
✅ /orders
✅ /products
❌ /user
❌ /order

✅ /user-profiles
✅ /order-items
❌ /user_profiles
❌ /orderItems

✅ /users/123/orders          (orders belonging to user 123)
✅ /orders/456/items          (items in order 456)
❌ /getUserOrders?userId=123

✅ /users?role=admin&sort=created_at&order=desc&page=2&limit=10
❌ /users/admin/sorted-by-date/page-2

Complete Router Implementation

go
// Filename: internal/router/router.go
package router

import (
    "net/http"

    "myapi/internal/handler"
    "myapi/internal/middleware"
)

// Config holds router dependencies
type Config struct {
    UserHandler   *handler.UserHandler
    OrderHandler  *handler.OrderHandler
    HealthHandler *handler.HealthHandler
    AuthMW        *middleware.AuthMiddleware
    RateLimitMW   *middleware.RateLimitMiddleware
    LoggingMW     *middleware.LoggingMiddleware
    RecoveryMW    *middleware.RecoveryMiddleware
    CORSMW        *middleware.CORSMiddleware
}

// New creates and configures the router
// Why: Centralizing route definitions makes the API structure clear
// and ensures consistent middleware application.
func New(cfg Config) http.Handler {
    mux := http.NewServeMux()

    // Health check endpoints (no auth required)
    // Why: Load balancers and orchestrators need to check health
    mux.HandleFunc("GET /health", cfg.HealthHandler.Health)
    mux.HandleFunc("GET /ready", cfg.HealthHandler.Ready)

    // API v1 routes
    // Why: Version prefix allows breaking changes in future versions

    // Public routes (no authentication)
    mux.HandleFunc("POST /api/v1/auth/login", cfg.UserHandler.Login)
    mux.HandleFunc("POST /api/v1/auth/register", cfg.UserHandler.Register)
    mux.HandleFunc("POST /api/v1/auth/refresh", cfg.UserHandler.RefreshToken)

    // Protected routes (authentication required)
    // Why: Using separate handler registration allows middleware chaining
    mux.Handle("GET /api/v1/users",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.UserHandler.ListUsers)))
    mux.Handle("POST /api/v1/users",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.UserHandler.CreateUser)))
    mux.Handle("GET /api/v1/users/{id}",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.UserHandler.GetUser)))
    mux.Handle("PUT /api/v1/users/{id}",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.UserHandler.ReplaceUser)))
    mux.Handle("PATCH /api/v1/users/{id}",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.UserHandler.UpdateUser)))
    mux.Handle("DELETE /api/v1/users/{id}",
        cfg.AuthMW.Authenticate(
            cfg.AuthMW.RequireRole("admin")(
                http.HandlerFunc(cfg.UserHandler.DeleteUser))))

    // Nested resources
    mux.Handle("GET /api/v1/users/{id}/orders",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.OrderHandler.GetUserOrders)))
    mux.Handle("POST /api/v1/users/{id}/orders",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.OrderHandler.CreateOrder)))

    // Order routes
    mux.Handle("GET /api/v1/orders",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.OrderHandler.ListOrders)))
    mux.Handle("GET /api/v1/orders/{id}",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.OrderHandler.GetOrder)))
    mux.Handle("POST /api/v1/orders/{id}/cancel",
        cfg.AuthMW.Authenticate(http.HandlerFunc(cfg.OrderHandler.CancelOrder)))

    // Apply global middleware chain
    // Why: Middleware order matters!
    // 1. Recovery: Catch panics first (outermost)
    // 2. CORS: Handle preflight before other processing
    // 3. Logging: Log all requests
    // 4. RateLimit: Protect before expensive operations
    var handler http.Handler = mux
    handler = cfg.RateLimitMW.Limit(handler)
    handler = cfg.LoggingMW.Log(handler)
    handler = cfg.CORSMW.Handle(handler)
    handler = cfg.RecoveryMW.Recover(handler)

    return handler
}

Middleware: The Unsung Heroes

REST API architecture diagram 5

Recovery Middleware: Catching Panics

go
// Filename: internal/middleware/recovery.go
package middleware

import (
    "log/slog"
    "net/http"
    "runtime/debug"

    "myapi/internal/pkg/response"
)

// RecoveryMiddleware recovers from panics
// Why: Panics in handlers shouldn't crash the entire server.
// This middleware catches panics, logs them, and returns a proper error.
type RecoveryMiddleware struct {
    logger *slog.Logger
}

func NewRecoveryMiddleware(logger *slog.Logger) *RecoveryMiddleware {
    return &RecoveryMiddleware{logger: logger}
}

// Recover wraps a handler with panic recovery
// Why: Without this, a panic in any handler would crash the server
// and leave the client hanging with no response.
func (m *RecoveryMiddleware) Recover(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                // Why: Log the full stack trace for debugging
                m.logger.Error("panic recovered",
                    "error", err,
                    "stack", string(debug.Stack()),
                    "path", r.URL.Path,
                    "method", r.Method,
                )

                // Why: Return 500 to client without exposing internal details
                response.Error(w, http.StatusInternalServerError,
                    "An unexpected error occurred")
            }
        }()

        next.ServeHTTP(w, r)
    })
}

Logging Middleware: Your Production Lifeline

go
// Filename: internal/middleware/logging.go
package middleware

import (
    "log/slog"
    "net/http"
    "time"
)

// LoggingMiddleware logs HTTP requests
// Why: Request logs are essential for debugging, auditing,
// and understanding traffic patterns.
type LoggingMiddleware struct {
    logger *slog.Logger
}

func NewLoggingMiddleware(logger *slog.Logger) *LoggingMiddleware {
    return &LoggingMiddleware{logger: logger}
}

// responseWriter wraps http.ResponseWriter to capture status code
// Why: The standard ResponseWriter doesn't expose the status code
// after it's been written, so we need to capture it.
type responseWriter struct {
    http.ResponseWriter
    status      int
    wroteHeader bool
    size        int
}

func wrapResponseWriter(w http.ResponseWriter) *responseWriter {
    return &responseWriter{ResponseWriter: w, status: http.StatusOK}
}

func (rw *responseWriter) WriteHeader(code int) {
    if rw.wroteHeader {
        return
    }
    rw.status = code
    rw.wroteHeader = true
    rw.ResponseWriter.WriteHeader(code)
}

func (rw *responseWriter) Write(b []byte) (int, error) {
    rw.size += len(b)
    return rw.ResponseWriter.Write(b)
}

// Log wraps a handler with request logging
// Why: Every request should be logged for:
// - Debugging issues
// - Auditing access
// - Performance monitoring
// - Security analysis
func (m *LoggingMiddleware) Log(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()

        // Why: Wrap response writer to capture status code and size
        wrapped := wrapResponseWriter(w)

        // Why: Extract request ID for correlation
        requestID := r.Header.Get("X-Request-ID")
        if requestID == "" {
            requestID = generateRequestID()
        }

        // Why: Add request ID to response for client correlation
        wrapped.Header().Set("X-Request-ID", requestID)

        // Process request
        next.ServeHTTP(wrapped, r)

        // Why: Calculate duration after request completes
        duration := time.Since(start)

        // Why: Log with structured fields for easy parsing
        m.logger.Info("http request",
            "request_id", requestID,
            "method", r.Method,
            "path", r.URL.Path,
            "query", r.URL.RawQuery,
            "status", wrapped.status,
            "duration_ms", duration.Milliseconds(),
            "size", wrapped.size,
            "user_agent", r.UserAgent(),
            "remote_addr", r.RemoteAddr,
        )
    })
}

func generateRequestID() string {
    // In production, use a proper UUID library
    return time.Now().UnixNano()
}

CORS Middleware: Handling Cross Origin Requests

go
// Filename: internal/middleware/cors.go
package middleware

import (
    "net/http"
    "strings"
)

// CORSConfig holds CORS configuration
type CORSConfig struct {
    AllowedOrigins   []string
    AllowedMethods   []string
    AllowedHeaders   []string
    ExposedHeaders   []string
    AllowCredentials bool
    MaxAge           int
}

// CORSMiddleware handles CORS
// Why: Browsers enforce CORS for security. Without proper CORS headers,
// frontend applications on different domains can't call your API.
type CORSMiddleware struct {
    config CORSConfig
}

func NewCORSMiddleware(config CORSConfig) *CORSMiddleware {
    return &CORSMiddleware{config: config}
}

// Handle adds CORS headers to responses
// Why: CORS involves two types of requests:
// 1. Simple requests: GET/POST with standard headers
// 2. Preflight requests: OPTIONS before complex requests
func (m *CORSMiddleware) Handle(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        origin := r.Header.Get("Origin")

        // Why: Check if origin is allowed
        if m.isOriginAllowed(origin) {
            w.Header().Set("Access-Control-Allow-Origin", origin)

            if m.config.AllowCredentials {
                // Why: Required for cookies/auth headers to be sent
                w.Header().Set("Access-Control-Allow-Credentials", "true")
            }

            // Why: Tell browser which headers it can access
            if len(m.config.ExposedHeaders) > 0 {
                w.Header().Set("Access-Control-Expose-Headers",
                    strings.Join(m.config.ExposedHeaders, ", "))
            }
        }

        // Why: Handle preflight OPTIONS request
        if r.Method == http.MethodOptions {
            // Why: Tell browser what methods are allowed
            w.Header().Set("Access-Control-Allow-Methods",
                strings.Join(m.config.AllowedMethods, ", "))

            // Why: Tell browser what headers can be sent
            w.Header().Set("Access-Control-Allow-Headers",
                strings.Join(m.config.AllowedHeaders, ", "))

            // Why: Cache preflight response to reduce OPTIONS requests
            if m.config.MaxAge > 0 {
                w.Header().Set("Access-Control-Max-Age",
                    string(m.config.MaxAge))
            }

            // Why: 204 for successful preflight, no body needed
            w.WriteHeader(http.StatusNoContent)
            return
        }

        next.ServeHTTP(w, r)
    })
}

func (m *CORSMiddleware) isOriginAllowed(origin string) bool {
    // Why: "*" means allow all origins (not recommended for production)
    for _, allowed := range m.config.AllowedOrigins {
        if allowed == "*" || allowed == origin {
            return true
        }
    }
    return false
}

Request Validation: Trust Nobody

💡 Think of it like this: A bank doesn't trust you just because you walked through the door. They verify your ID, check your signature, confirm your account number. Your API should do the same with every request.

REST API architecture diagram 6

Comprehensive Validation Implementation

go
// Filename: internal/pkg/validator/validator.go
package validator

import (
    "fmt"
    "net/mail"
    "regexp"
    "strings"
    "unicode"
)

// ValidationErrors holds field-level errors
// Why: Returning all errors at once is better UX than one at a time
type ValidationErrors map[string]string

func (v ValidationErrors) HasErrors() bool {
    return len(v) > 0
}

func (v ValidationErrors) Add(field, message string) {
    v[field] = message
}

// Validator provides validation methods
// Why: Centralizing validation logic ensures consistent rules
// across the application and makes testing easier.
type Validator struct {
    errors ValidationErrors
}

func New() *Validator {
    return &Validator{
        errors: make(ValidationErrors),
    }
}

func (v *Validator) Errors() ValidationErrors {
    return v.errors
}

// Required checks if a string is not empty
// Why: Most form fields require a value
func (v *Validator) Required(field, value, message string) *Validator {
    if strings.TrimSpace(value) == "" {
        v.errors.Add(field, message)
    }
    return v
}

// Email validates email format
// Why: Invalid emails cause delivery failures
func (v *Validator) Email(field, value string) *Validator {
    if value == "" {
        return v // Let Required handle empty check
    }

    _, err := mail.ParseAddress(value)
    if err != nil {
        v.errors.Add(field, "Invalid email format")
    }
    return v
}

// MinLength checks minimum string length
// Why: Passwords, usernames often have minimum lengths
func (v *Validator) MinLength(field, value string, min int) *Validator {
    if len(value) < min {
        v.errors.Add(field, fmt.Sprintf("Must be at least %d characters", min))
    }
    return v
}

// MaxLength checks maximum string length
// Why: Prevent database overflow and DoS via large inputs
func (v *Validator) MaxLength(field, value string, max int) *Validator {
    if len(value) > max {
        v.errors.Add(field, fmt.Sprintf("Must be at most %d characters", max))
    }
    return v
}

// Password validates password strength
// Why: Weak passwords are a security risk
func (v *Validator) Password(field, value string) *Validator {
    if len(value) < 8 {
        v.errors.Add(field, "Password must be at least 8 characters")
        return v
    }

    var hasUpper, hasLower, hasNumber, hasSpecial bool

    for _, char := range value {
        switch {
        case unicode.IsUpper(char):
            hasUpper = true
        case unicode.IsLower(char):
            hasLower = true
        case unicode.IsNumber(char):
            hasNumber = true
        case unicode.IsPunct(char) || unicode.IsSymbol(char):
            hasSpecial = true
        }
    }

    if !hasUpper || !hasLower || !hasNumber || !hasSpecial {
        v.errors.Add(field,
            "Password must contain uppercase, lowercase, number, and special character")
    }

    return v
}

// UUID validates UUID format
// Why: Invalid UUIDs will fail database lookups
func (v *Validator) UUID(field, value string) *Validator {
    uuidRegex := regexp.MustCompile(
        `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`)

    if !uuidRegex.MatchString(value) {
        v.errors.Add(field, "Invalid UUID format")
    }
    return v
}

// InList checks if value is in allowed list
// Why: Enum-like fields should only accept known values
func (v *Validator) InList(field, value string, allowed []string) *Validator {
    for _, a := range allowed {
        if value == a {
            return v
        }
    }
    v.errors.Add(field, fmt.Sprintf("Must be one of: %s", strings.Join(allowed, ", ")))
    return v
}

// Range checks if a number is within range
// Why: Quantities, prices, ages have valid ranges
func (v *Validator) Range(field string, value, min, max int) *Validator {
    if value < min || value > max {
        v.errors.Add(field, fmt.Sprintf("Must be between %d and %d", min, max))
    }
    return v
}

// Positive checks if number is positive
// Why: Prices, quantities can't be negative
func (v *Validator) Positive(field string, value int) *Validator {
    if value <= 0 {
        v.errors.Add(field, "Must be a positive number")
    }
    return v
}

// URL validates URL format
// Why: Invalid URLs break links and integrations
func (v *Validator) URL(field, value string) *Validator {
    if value == "" {
        return v
    }

    urlRegex := regexp.MustCompile(`^https?://[^\s/$.?#].[^\s]*$`)
    if !urlRegex.MatchString(value) {
        v.errors.Add(field, "Invalid URL format")
    }
    return v
}

// Phone validates phone number (basic validation)
// Why: Invalid phone numbers can't receive SMS
func (v *Validator) Phone(field, value string) *Validator {
    if value == "" {
        return v
    }

    // Remove common formatting characters
    cleaned := regexp.MustCompile(`[\s\-\(\)\+]`).ReplaceAllString(value, "")

    if len(cleaned) < 10 || len(cleaned) > 15 {
        v.errors.Add(field, "Invalid phone number")
    }
    return v
}

Using Validation in Handlers

go
// Filename: internal/handler/user_handler.go (continued)
package handler

import (
    "encoding/json"
    "net/http"

    "myapi/internal/pkg/response"
    "myapi/internal/pkg/validator"
)

// CreateUser with full validation
func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
    // Step 1: Parse request body
    // Why: Decode JSON first, then validate fields
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        response.Error(w, http.StatusBadRequest, "Invalid JSON")
        return
    }

    // Step 2: Validate all fields
    // Why: Chain validations for clean code, collect all errors
    v := validator.New()
    v.Required("email", req.Email, "Email is required").
        Email("email", req.Email)
    v.Required("name", req.Name, "Name is required").
        MinLength("name", req.Name, 2).
        MaxLength("name", req.Name, 100)
    v.Required("password", req.Password, "Password is required").
        Password("password", req.Password)
    v.Required("role", req.Role, "Role is required").
        InList("role", req.Role, []string{"admin", "user", "guest"})

    // Step 3: Return validation errors if any
    // Why: Return all errors at once for better UX
    if v.Errors().HasErrors() {
        response.ValidationError(w, v.Errors())
        return
    }

    // Step 4: Process valid request
    // Why: Now we can trust the input
    user, err := h.service.CreateUser(
        r.Context(),
        req.Email,
        req.Name,
        req.Password,
        req.Role,
    )
    if err != nil {
        // Why: Handle business logic errors (e.g., duplicate email)
        response.Error(w, http.StatusConflict, err.Error())
        return
    }

    w.Header().Set("Location", "/api/v1/users/"+user.ID)
    response.JSON(w, http.StatusCreated, user)
}

type CreateUserRequest struct {
    Email    string `json:"email"`
    Name     string `json:"name"`
    Password string `json:"password"`
    Role     string `json:"role"`
}

Error Handling: Failing Gracefully

REST API architecture diagram 7

Custom Error Types

go
// Filename: internal/pkg/errors/errors.go
package errors

import (
    "errors"
    "fmt"
    "net/http"
)

// AppError represents an application error
// Why: Custom error type allows us to:
// 1. Include HTTP status code
// 2. Separate internal and external messages
// 3. Add context like error codes
type AppError struct {
    Code       string // Machine-readable code
    Message    string // User-friendly message
    Internal   string // Internal details (logged, not returned)
    StatusCode int    // HTTP status code
    Err        error  // Wrapped error for error chain
}

func (e *AppError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("%s: %v", e.Message, e.Err)
    }
    return e.Message
}

// Unwrap allows errors.Is and errors.As to work
func (e *AppError) Unwrap() error {
    return e.Err
}

// Error constructors for common cases
// Why: Consistent error creation across the codebase

func NotFound(resource string) *AppError {
    return &AppError{
        Code:       "NOT_FOUND",
        Message:    fmt.Sprintf("%s not found", resource),
        StatusCode: http.StatusNotFound,
    }
}

func BadRequest(message string) *AppError {
    return &AppError{
        Code:       "BAD_REQUEST",
        Message:    message,
        StatusCode: http.StatusBadRequest,
    }
}

func Unauthorized(message string) *AppError {
    return &AppError{
        Code:       "UNAUTHORIZED",
        Message:    message,
        StatusCode: http.StatusUnauthorized,
    }
}

func Forbidden(message string) *AppError {
    return &AppError{
        Code:       "FORBIDDEN",
        Message:    message,
        StatusCode: http.StatusForbidden,
    }
}

func Conflict(message string) *AppError {
    return &AppError{
        Code:       "CONFLICT",
        Message:    message,
        StatusCode: http.StatusConflict,
    }
}

func InternalError(internal string, err error) *AppError {
    return &AppError{
        Code:       "INTERNAL_ERROR",
        Message:    "An internal error occurred",
        Internal:   internal,
        StatusCode: http.StatusInternalServerError,
        Err:        err,
    }
}

func DatabaseError(operation string, err error) *AppError {
    return &AppError{
        Code:       "DATABASE_ERROR",
        Message:    "A database error occurred",
        Internal:   fmt.Sprintf("database %s failed", operation),
        StatusCode: http.StatusInternalServerError,
        Err:        err,
    }
}

func ServiceUnavailable(service string) *AppError {
    return &AppError{
        Code:       "SERVICE_UNAVAILABLE",
        Message:    fmt.Sprintf("%s is currently unavailable", service),
        StatusCode: http.StatusServiceUnavailable,
    }
}

func RateLimited() *AppError {
    return &AppError{
        Code:       "RATE_LIMITED",
        Message:    "Too many requests. Please try again later.",
        StatusCode: http.StatusTooManyRequests,
    }
}

// IsNotFound checks if error is a not found error
// Why: Allow callers to check error type without type assertion
func IsNotFound(err error) bool {
    var appErr *AppError
    if errors.As(err, &appErr) {
        return appErr.Code == "NOT_FOUND"
    }
    return false
}

// IsConflict checks if error is a conflict error
func IsConflict(err error) bool {
    var appErr *AppError
    if errors.As(err, &appErr) {
        return appErr.Code == "CONFLICT"
    }
    return false
}

Error Handling Middleware

go
// Filename: internal/middleware/error_handler.go
package middleware

import (
    "errors"
    "log/slog"
    "net/http"

    apperrors "myapi/internal/pkg/errors"
    "myapi/internal/pkg/response"
)

// ErrorHandler is a middleware that handles errors returned by handlers
// Why: Centralizes error response formatting and logging
type ErrorHandler struct {
    logger *slog.Logger
}

func NewErrorHandler(logger *slog.Logger) *ErrorHandler {
    return &ErrorHandler{logger: logger}
}

// HandleError processes an error and sends appropriate response
// Why: Single point for error response logic
func (h *ErrorHandler) HandleError(w http.ResponseWriter, r *http.Request, err error) {
    // Why: Check if it's our custom AppError
    var appErr *apperrors.AppError
    if errors.As(err, &appErr) {
        // Log internal details if present
        if appErr.Internal != "" {
            h.logger.Error("application error",
                "code", appErr.Code,
                "message", appErr.Message,
                "internal", appErr.Internal,
                "path", r.URL.Path,
                "method", r.Method,
            )
        }

        // Return sanitized error to client
        response.Error(w, appErr.StatusCode, appErr.Message)
        return
    }

    // Why: Unknown errors get logged with full details
    h.logger.Error("unexpected error",
        "error", err.Error(),
        "path", r.URL.Path,
        "method", r.Method,
    )

    // Why: Don't expose internal error details to client
    response.Error(w, http.StatusInternalServerError,
        "An unexpected error occurred")
}

Authentication: Who Are You?

REST API architecture diagram 8

JWT Authentication Implementation

go
// Filename: internal/auth/jwt.go
package auth

import (
    "errors"
    "time"

    "github.com/golang-jwt/jwt/v5"
)

// TokenConfig holds JWT configuration
type TokenConfig struct {
    SecretKey          string
    AccessTokenExpiry  time.Duration
    RefreshTokenExpiry time.Duration
    Issuer             string
}

// Claims represents JWT claims
// Why: Custom claims allow us to include user info in the token,
// avoiding database lookups for every authenticated request.
type Claims struct {
    UserID string `json:"user_id"`
    Email  string `json:"email"`
    Role   string `json:"role"`
    jwt.RegisteredClaims
}

// TokenPair holds access and refresh tokens
type TokenPair struct {
    AccessToken  string `json:"access_token"`
    RefreshToken string `json:"refresh_token"`
    ExpiresIn    int64  `json:"expires_in"` // Seconds until access token expires
}

// JWTService handles JWT operations
// Why: Encapsulating JWT logic makes it easy to:
// 1. Test token generation/validation
// 2. Switch to different token libraries
// 3. Change token configuration
type JWTService struct {
    config TokenConfig
}

func NewJWTService(config TokenConfig) *JWTService {
    return &JWTService{config: config}
}

// GenerateTokenPair creates access and refresh tokens
// Why: Access tokens are short-lived for security.
// Refresh tokens allow getting new access tokens without re-login.
func (s *JWTService) GenerateTokenPair(userID, email, role string) (*TokenPair, error) {
    now := time.Now()

    // Create access token
    // Why: Short expiry (15 min) limits damage if token is stolen
    accessClaims := Claims{
        UserID: userID,
        Email:  email,
        Role:   role,
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(now.Add(s.config.AccessTokenExpiry)),
            IssuedAt:  jwt.NewNumericDate(now),
            NotBefore: jwt.NewNumericDate(now),
            Issuer:    s.config.Issuer,
            Subject:   userID,
        },
    }

    accessToken := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims)
    accessTokenString, err := accessToken.SignedString([]byte(s.config.SecretKey))
    if err != nil {
        return nil, err
    }

    // Create refresh token
    // Why: Longer expiry (7 days) for convenience
    // Contains minimal claims for security
    refreshClaims := jwt.RegisteredClaims{
        ExpiresAt: jwt.NewNumericDate(now.Add(s.config.RefreshTokenExpiry)),
        IssuedAt:  jwt.NewNumericDate(now),
        NotBefore: jwt.NewNumericDate(now),
        Issuer:    s.config.Issuer,
        Subject:   userID,
    }

    refreshToken := jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims)
    refreshTokenString, err := refreshToken.SignedString([]byte(s.config.SecretKey))
    if err != nil {
        return nil, err
    }

    return &TokenPair{
        AccessToken:  accessTokenString,
        RefreshToken: refreshTokenString,
        ExpiresIn:    int64(s.config.AccessTokenExpiry.Seconds()),
    }, nil
}

// ValidateAccessToken validates and parses an access token
// Why: Every authenticated request needs token validation
func (s *JWTService) ValidateAccessToken(tokenString string) (*Claims, error) {
    token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
        // Why: Verify signing method to prevent algorithm confusion attacks
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, errors.New("unexpected signing method")
        }
        return []byte(s.config.SecretKey), nil
    })

    if err != nil {
        return nil, err
    }

    claims, ok := token.Claims.(*Claims)
    if !ok || !token.Valid {
        return nil, errors.New("invalid token")
    }

    return claims, nil
}

// ValidateRefreshToken validates a refresh token and returns the user ID
// Why: Refresh tokens have different claims structure
func (s *JWTService) ValidateRefreshToken(tokenString string) (string, error) {
    token, err := jwt.ParseWithClaims(tokenString, &jwt.RegisteredClaims{}, func(token *jwt.Token) (interface{}, error) {
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, errors.New("unexpected signing method")
        }
        return []byte(s.config.SecretKey), nil
    })

    if err != nil {
        return "", err
    }

    claims, ok := token.Claims.(*jwt.RegisteredClaims)
    if !ok || !token.Valid {
        return "", errors.New("invalid token")
    }

    return claims.Subject, nil
}