DEV Community: Edgar Nahama Alochi

Routing in Go Part 3: The last upgrade

Edgar Nahama Alochi — Sat, 22 Aug 2026 20:35:24 +0000

Part 3: The last upgrade

Pagination, update endpoint, request scoped logging, and lightweight OpenAPI

By now we have a small Go API that is not embarrassing.

We have routes, a service layer, middleware, timeouts, and tests. That is already better than most code that ships.

For the last part, we are going to add the stuff that turns “cute demo” into “this could actually run”:

Pagination for GET /links
PUT /links/{id} to update the note
Structured enough logging so you can trace a request without reading tea leaves
A small OpenAPI spec so other people do not have to guess your API

Still simple. Still standard library.

Step 1: Add pagination to the store and service

We will do offset pagination because it is easy to understand. Cursor pagination is better at scale, but you can add it later when you actually have scale. Most people add it early as a personality trait.

Update `internal/links/store.go`

Replace the Store interface and add a paginated list method. Also update the memory store.

package links

import (
    "sort"
    "sync"
    "time"
)

type Store interface {
    Create(amount int, currency, note string) PayLink
    Get(id int) (PayLink, bool)
    UpdateNote(id int, note string) (PayLink, bool)
    List(offset, limit int) []PayLink
    Count() int
}

type MemoryStore struct {
    mu    sync.RWMutex
    next  int
    links map[int]PayLink
}

func NewMemoryStore() *MemoryStore {
    return &MemoryStore{
        next:  1,
        links: make(map[int]PayLink),
    }
}

func (s *MemoryStore) Create(amount int, currency, note string) PayLink {
    s.mu.Lock()
    defer s.mu.Unlock()

    l := PayLink{
        ID:        s.next,
        Amount:    amount,
        Currency:  currency,
        Note:      note,
        CreatedAt: time.Now().UTC(),
    }
    s.links[l.ID] = l
    s.next++
    return l
}

func (s *MemoryStore) Get(id int) (PayLink, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    l, ok := s.links[id]
    return l, ok
}

func (s *MemoryStore) UpdateNote(id int, note string) (PayLink, bool) {
    s.mu.Lock()
    defer s.mu.Unlock()

    l, ok := s.links[id]
    if !ok {
        return PayLink{}, false
    }
    l.Note = note
    s.links[id] = l
    return l, true
}

func (s *MemoryStore) Count() int {
    s.mu.RLock()
    defer s.mu.RUnlock()
    return len(s.links)
}

func (s *MemoryStore) List(offset, limit int) []PayLink {
    s.mu.RLock()
    defer s.mu.RUnlock()

    if offset < 0 {
        offset = 0
    }
    if limit <= 0 {
        limit = 20
    }
    if limit > 100 {
        limit = 100
    }

    ids := make([]int, 0, len(s.links))
    for id := range s.links {
        ids = append(ids, id)
    }
    sort.Ints(ids)

    if offset >= len(ids) {
        return []PayLink{}
    }

    end := offset + limit
    if end > len(ids) {
        end = len(ids)
    }

    out := make([]PayLink, 0, end-offset)
    for _, id := range ids[offset:end] {
        out = append(out, s.links[id])
    }
    return out
}

Now update the service so handlers do not have to know pagination rules.

Update `internal/links/service.go`

Add these methods and errors.

package links

import (
    "context"
    "errors"
    "strings"
)

var (
    ErrInvalidAmount   = errors.New("amount must be greater than zero")
    ErrInvalidCurrency = errors.New("currency must be a 3 letter code like USD")
    ErrInvalidLimit    = errors.New("limit must be between 1 and 100")
    ErrInvalidOffset   = errors.New("offset must be 0 or greater")
    ErrNotFound        = errors.New("link not found")
)

type Service struct {
    store Store
}

func NewService(store Store) *Service {
    return &Service{store: store}
}

func (s *Service) Create(ctx context.Context, amount int, currency, note string) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }

    currency = strings.ToUpper(strings.TrimSpace(currency))
    note = strings.TrimSpace(note)

    if amount <= 0 {
        return PayLink{}, ErrInvalidAmount
    }
    if len(currency) != 3 {
        return PayLink{}, ErrInvalidCurrency
    }
    return s.store.Create(amount, currency, note), nil
}

type Page struct {
    Items  []PayLink `json:"items"`
    Total  int       `json:"total"`
    Offset int       `json:"offset"`
    Limit  int       `json:"limit"`
}

func (s *Service) ListPage(ctx context.Context, offset, limit int) (Page, error) {
    select {
    case <-ctx.Done():
        return Page{}, ctx.Err()
    default:
    }

    if offset < 0 {
        return Page{}, ErrInvalidOffset
    }
    if limit <= 0 || limit > 100 {
        return Page{}, ErrInvalidLimit
    }

    return Page{
        Items:  s.store.List(offset, limit),
        Total:  s.store.Count(),
        Offset: offset,
        Limit:  limit,
    }, nil
}

func (s *Service) Get(ctx context.Context, id int) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }
    l, ok := s.store.Get(id)
    if !ok {
        return PayLink{}, ErrNotFound
    }
    return l, nil
}

func (s *Service) UpdateNote(ctx context.Context, id int, note string) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }

    note = strings.TrimSpace(note)
    if note == "" {
        // Keep it simple. You can allow empty later if needed.
        return PayLink{}, errors.New("note is required")
    }

    l, ok := s.store.UpdateNote(id, note)
    if !ok {
        return PayLink{}, ErrNotFound
    }
    return l, nil
}

Step 2: Add request scoped logging that actually helps

Right now we log method, path, and duration. Good start.

Let us add request ID into the logs and also return it in error responses. Because when a user reports a bug, you want them to give you one string, not a full emotional experience.

Update `internal/httpapi/helpers.go`

package httpapi

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

func WriteJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func WriteError(w http.ResponseWriter, status int, msg string) {
    reqID := w.Header().Get("X-Request-Id")
    if reqID == "" {
        WriteJSON(w, status, map[string]string{"error": msg})
        return
    }
    WriteJSON(w, status, map[string]string{"error": msg, "request_id": reqID})
}

Update `internal/httpapi/middleware.go`

Change the logging middleware to include request id.

func Logging(logger *log.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)

            reqID := w.Header().Get("X-Request-Id")
            if reqID == "" {
                reqID = "-"
            }

            logger.Printf("rid=%s %s %s from=%s dur=%s",
                reqID,
                r.Method,
                r.URL.Path,
                clientIP(r),
                time.Since(start).Round(time.Millisecond),
            )
        })
    }
}

Now your logs are traceable.

Step 3: Update handlers for pagination and PUT

Update `internal/httpapi/handlers.go`

Replace the collection handler and add a new update handler.

package httpapi

import (
    "context"
    "encoding/json"
    "errors"
    "net/http"
    "strconv"
    "time"

    "example.com/paylinks/internal/links"
)

type API struct {
    Links *links.Service
}

func (a *API) Routes() http.Handler {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        WriteJSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    mux.HandleFunc("/links", a.linksCollection)
    mux.HandleFunc("GET /links/{id}", a.linksGet)
    mux.HandleFunc("PUT /links/{id}", a.linksUpdateNote)

    return mux
}

func (a *API) linksCollection(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    switch r.Method {
    case http.MethodGet:
        offset := parseIntQuery(r, "offset", 0)
        limit := parseIntQuery(r, "limit", 20)

        page, err := a.Links.ListPage(ctx, offset, limit)
        if err != nil {
            switch {
            case errors.Is(err, links.ErrInvalidOffset), errors.Is(err, links.ErrInvalidLimit):
                WriteError(w, http.StatusBadRequest, err.Error())
            case errors.Is(err, context.DeadlineExceeded):
                WriteError(w, http.StatusRequestTimeout, "request timed out")
            default:
                WriteError(w, http.StatusInternalServerError, "server error")
            }
            return
        }

        WriteJSON(w, http.StatusOK, page)
        return

    case http.MethodPost:
        var body struct {
            Amount   int    `json:"amount"`
            Currency string `json:"currency"`
            Note     string `json:"note"`
        }
        if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
            WriteError(w, http.StatusBadRequest, "invalid JSON body")
            return
        }

        l, err := a.Links.Create(ctx, body.Amount, body.Currency, body.Note)
        if err != nil {
            switch {
            case errors.Is(err, links.ErrInvalidAmount), errors.Is(err, links.ErrInvalidCurrency):
                WriteError(w, http.StatusBadRequest, err.Error())
            case errors.Is(err, context.DeadlineExceeded):
                WriteError(w, http.StatusRequestTimeout, "request timed out")
            default:
                WriteError(w, http.StatusInternalServerError, "server error")
            }
            return
        }

        WriteJSON(w, http.StatusCreated, l)
        return

    default:
        WriteError(w, http.StatusMethodNotAllowed, "method not allowed")
        return
    }
}

func (a *API) linksGet(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    idStr := r.PathValue("id")
    id, err := strconv.Atoi(idStr)
    if err != nil || id <= 0 {
        WriteError(w, http.StatusBadRequest, "invalid link id")
        return
    }

    l, err := a.Links.Get(ctx, id)
    if err != nil {
        switch {
        case errors.Is(err, links.ErrNotFound):
            WriteError(w, http.StatusNotFound, "link not found")
        case errors.Is(err, context.DeadlineExceeded):
            WriteError(w, http.StatusRequestTimeout, "request timed out")
        default:
            WriteError(w, http.StatusInternalServerError, "server error")
        }
        return
    }

    WriteJSON(w, http.StatusOK, l)
}

func (a *API) linksUpdateNote(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    idStr := r.PathValue("id")
    id, err := strconv.Atoi(idStr)
    if err != nil || id <= 0 {
        WriteError(w, http.StatusBadRequest, "invalid link id")
        return
    }

    var body struct {
        Note string `json:"note"`
    }
    if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
        WriteError(w, http.StatusBadRequest, "invalid JSON body")
        return
    }

    l, err := a.Links.UpdateNote(ctx, id, body.Note)
    if err != nil {
        switch {
        case errors.Is(err, links.ErrNotFound):
            WriteError(w, http.StatusNotFound, "link not found")
        default:
            WriteError(w, http.StatusBadRequest, err.Error())
        }
        return
    }

    WriteJSON(w, http.StatusOK, l)
}

func parseIntQuery(r *http.Request, key string, fallback int) int {
    raw := r.URL.Query().Get(key)
    if raw == "" {
        return fallback
    }
    v, err := strconv.Atoi(raw)
    if err != nil {
        return fallback
    }
    return v
}

Now you have:

GET /links?offset=0&limit=20
PUT /links/1 with body {"note":"new note"}

Step 4: Update tests for the new behavior

Update internal/httpapi/handlers_test.go by adding these tests.

func TestPagination(t *testing.T) {
    h := newTestServer()

    // Create 3 items
    for i := 0; i < 3; i++ {
        body := []byte(`{"amount":100,"currency":"usd","note":"x"}`)
        req := httptest.NewRequest(http.MethodPost, "/links", bytes.NewReader(body))
        req.Header.Set("Content-Type", "application/json")
        rec := httptest.NewRecorder()
        h.ServeHTTP(rec, req)

        if rec.Code != http.StatusCreated {
            t.Fatalf("expected 201, got %d body=%s", rec.Code, rec.Body.String())
        }
    }

    // Fetch page with limit=2
    req := httptest.NewRequest(http.MethodGet, "/links?offset=0&limit=2", nil)
    rec := httptest.NewRecorder()
    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d body=%s", rec.Code, rec.Body.String())
    }
}

func TestUpdateNote(t *testing.T) {
    h := newTestServer()

    // Create
    body := []byte(`{"amount":5000,"currency":"kes","note":"old"}`)
    req := httptest.NewRequest(http.MethodPost, "/links", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    rec := httptest.NewRecorder()
    h.ServeHTTP(rec, req)
    if rec.Code != http.StatusCreated {
        t.Fatalf("expected 201, got %d body=%s", rec.Code, rec.Body.String())
    }

    // Update
    up := []byte(`{"note":"new note"}`)
    req2 := httptest.NewRequest(http.MethodPut, "/links/1", bytes.NewReader(up))
    req2.Header.Set("Content-Type", "application/json")
    rec2 := httptest.NewRecorder()
    h.ServeHTTP(rec2, req2)

    if rec2.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d body=%s", rec2.Code, rec2.Body.String())
    }
}

Run:

go test ./...

Step 5: Add an OpenAPI spec without turning into a bureaucracy

This is where teams often go wrong.

They either have no docs and everyone guesses, or they treat OpenAPI like a sacred ritual and stop shipping.

We will do a lightweight OpenAPI file by hand. Just enough so someone can integrate without calling you.

Create openapi.yaml at the project root.

openapi: 3.0.3
info:
  title: PayLinks API
  version: 1.0.0
servers:
  - url: http://localhost:8080
paths:
  /health:
    get:
      summary: Health check
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
  /links:
    get:
      summary: List payment links
      parameters:
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
          required: false
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
          required: false
      responses:
        "200":
          description: Paginated list
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/PayLink"
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
    post:
      summary: Create a payment link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, currency]
              properties:
                amount:
                  type: integer
                  minimum: 1
                currency:
                  type: string
                  example: USD
                note:
                  type: string
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayLink"
  /links/{id}:
    get:
      summary: Get one payment link
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayLink"
        "404":
          description: Not found
    put:
      summary: Update the note for a payment link
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [note]
              properties:
                note:
                  type: string
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayLink"
components:
  schemas:
    PayLink:
      type: object
      properties:
        id:
          type: integer
        amount:
          type: integer
        currency:
          type: string
        note:
          type: string
        created_at:
          type: string
          format: date-time

Now your API has a contract.

Not perfect. Not automatic. But good enough to stop people from guessing.

Quick manual smoke test for Part 3

Run the server:

API_KEY=supersecret go run ./cmd/api

Create a few links:

curl -s -X POST http://localhost:8080/links \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"amount":1200,"currency":"usd","note":"coffee"}'

curl -s -X POST http://localhost:8080/links \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"amount":9000,"currency":"kes","note":"invoice 22"}'

List with pagination:

curl -s "http://localhost:8080/links?offset=0&limit=1" -H "X-API-Key: supersecret"

Update note:

curl -s -X PUT http://localhost:8080/links/1 \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"note":"coffee, but make it urgent"}'

The real takeaway

If you remember one thing from all three parts, make it this:

Routing is not the hard part. The hard part is not letting routing become your entire application.

Keep handlers thin. Put rules in a service. Put shared behavior in middleware. Add tests early. Add docs before you forget what your API does.

This is how you build a Go server that does not require a rewrite the moment it gets real traffic.

And yes, you will still rewrite parts of it later. But it will be because you chose to, not because the code forced you into a corner with a chair.

Routing in Go Part 2: Upgrading the server so it behaves like a grown up

Edgar Nahama Alochi — Sat, 22 Aug 2026 20:34:53 +0000

Part 2: Upgrading the server

Tests, auth middleware, a service layer, and request timeouts

In part 1 we built a small payment links API.

In part 2 we are going to do the things everyone promises they will do “after launch” and then never do until something catches fire.

We will add:

A service layer so handlers stop doing business decisions
Auth middleware with a simple API key
Request scoped timeouts so slow work does not hang forever
Proper handler tests with httptest

Same rule as before. No magic. Code that compiles.

Step 1: Restructure into a sane layout

Keep it small, but separate responsibilities.

Create this structure:

mkdir -p cmd/api internal/httpapi internal/links

You will end up with:

cmd/api/main.go bootstraps the server
internal/httpapi routing, middleware, helpers
internal/links store and service logic

Step 2: Move the domain and store into `internal/links`

Create internal/links/model.go

package links

import "time"

type PayLink struct {
    ID        int       `json:"id"`
    Amount    int       `json:"amount"`
    Currency  string    `json:"currency"`
    Note      string    `json:"note"`
    CreatedAt time.Time `json:"created_at"`
}

Create internal/links/store.go

package links

import (
    "sync"
    "time"
)

type Store interface {
    Create(amount int, currency, note string) PayLink
    List() []PayLink
    Get(id int) (PayLink, bool)
}

type MemoryStore struct {
    mu    sync.RWMutex
    next  int
    links map[int]PayLink
}

func NewMemoryStore() *MemoryStore {
    return &MemoryStore{
        next:  1,
        links: make(map[int]PayLink),
    }
}

func (s *MemoryStore) Create(amount int, currency, note string) PayLink {
    s.mu.Lock()
    defer s.mu.Unlock()

    l := PayLink{
        ID:        s.next,
        Amount:    amount,
        Currency:  currency,
        Note:      note,
        CreatedAt: time.Now().UTC(),
    }
    s.links[l.ID] = l
    s.next++
    return l
}

func (s *MemoryStore) List() []PayLink {
    s.mu.RLock()
    defer s.mu.RUnlock()

    out := make([]PayLink, 0, len(s.links))
    for _, l := range s.links {
        out = append(out, l)
    }
    return out
}

func (s *MemoryStore) Get(id int) (PayLink, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    l, ok := s.links[id]
    return l, ok
}

Step 3: Add a service layer that owns the rules

This is where you put “currency must be 3 letters” and “amount must be positive”.

Create internal/links/service.go

package links

import (
    "context"
    "errors"
    "strings"
    "time"
)

var (
    ErrInvalidAmount   = errors.New("amount must be greater than zero")
    ErrInvalidCurrency = errors.New("currency must be a 3 letter code like USD")
    ErrNotFound        = errors.New("link not found")
)

type Service struct {
    store Store
}

func NewService(store Store) *Service {
    return &Service{store: store}
}

func (s *Service) Create(ctx context.Context, amount int, currency, note string) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }

    currency = strings.ToUpper(strings.TrimSpace(currency))
    note = strings.TrimSpace(note)

    if amount <= 0 {
        return PayLink{}, ErrInvalidAmount
    }
    if len(currency) != 3 {
        return PayLink{}, ErrInvalidCurrency
    }

    // Pretend we might do more work here later.
    time.Sleep(5 * time.Millisecond)

    return s.store.Create(amount, currency, note), nil
}

func (s *Service) List(ctx context.Context) ([]PayLink, error) {
    select {
    case <-ctx.Done():
        return nil, ctx.Err()
    default:
    }
    return s.store.List(), nil
}

func (s *Service) Get(ctx context.Context, id int) (PayLink, error) {
    select {
    case <-ctx.Done():
        return PayLink{}, ctx.Err()
    default:
    }
    l, ok := s.store.Get(id)
    if !ok {
        return PayLink{}, ErrNotFound
    }
    return l, nil
}

Notice what happened.

Handlers no longer need to know the rules. They only translate HTTP into method calls.

That is how you stop your routing from turning into a soap opera.

Step 4: HTTP helpers and middleware

Create internal/httpapi/helpers.go

package httpapi

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

func WriteJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func WriteError(w http.ResponseWriter, status int, msg string) {
    WriteJSON(w, status, map[string]string{"error": msg})
}

Create internal/httpapi/middleware.go

package httpapi

import (
    "log"
    "math/rand"
    "net"
    "net/http"
    "strconv"
    "strings"
    "time"
)

type Middleware func(http.Handler) http.Handler

func Chain(h http.Handler, m ...Middleware) http.Handler {
    for i := len(m) - 1; i >= 0; i-- {
        h = m[i](h)
    }
    return h
}

func RequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" {
            id = newRequestID()
        }
        w.Header().Set("X-Request-Id", id)
        next.ServeHTTP(w, r)
    })
}

func Logging(logger *log.Logger) Middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)
            logger.Printf("%s %s from=%s dur=%s",
                r.Method,
                r.URL.Path,
                clientIP(r),
                time.Since(start).Round(time.Millisecond),
            )
        })
    }
}

func APIKeyAuth(expected string) Middleware {
    expected = strings.TrimSpace(expected)
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // Let health stay public. Your uptime monitor is not your enemy.
            if r.URL.Path == "/health" {
                next.ServeHTTP(w, r)
                return
            }

            if expected == "" {
                // If no key is configured, do not pretend you are secure.
                WriteError(w, http.StatusInternalServerError, "server missing API key configuration")
                return
            }

            got := strings.TrimSpace(r.Header.Get("X-API-Key"))
            if got != expected {
                WriteError(w, http.StatusUnauthorized, "unauthorized")
                return
            }

            next.ServeHTTP(w, r)
        })
    }
}

func clientIP(r *http.Request) string {
    host, _, err := net.SplitHostPort(r.RemoteAddr)
    if err != nil {
        return r.RemoteAddr
    }
    return host
}

func newRequestID() string {
    return strconv.FormatInt(time.Now().UnixNano(), 36) + "-" + strconv.Itoa(rand.Intn(1000000))
}

Step 5: Handlers that use the service layer

Create internal/httpapi/handlers.go

package httpapi

import (
    "context"
    "encoding/json"
    "errors"
    "net/http"
    "strconv"
    "time"

    "example.com/paylinks/internal/links"
)

type API struct {
    Links *links.Service
}

func (a *API) Routes() http.Handler {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        WriteJSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    mux.HandleFunc("/links", a.linksCollection)
    mux.HandleFunc("GET /links/{id}", a.linksGet)

    return mux
}

func (a *API) linksCollection(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    switch r.Method {
    case http.MethodGet:
        items, err := a.Links.List(ctx)
        if err != nil {
            WriteError(w, http.StatusRequestTimeout, "request timed out")
            return
        }
        WriteJSON(w, http.StatusOK, items)
        return

    case http.MethodPost:
        var body struct {
            Amount   int    `json:"amount"`
            Currency string `json:"currency"`
            Note     string `json:"note"`
        }
        if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
            WriteError(w, http.StatusBadRequest, "invalid JSON body")
            return
        }

        l, err := a.Links.Create(ctx, body.Amount, body.Currency, body.Note)
        if err != nil {
            switch {
            case errors.Is(err, links.ErrInvalidAmount), errors.Is(err, links.ErrInvalidCurrency):
                WriteError(w, http.StatusBadRequest, err.Error())
            case errors.Is(err, context.DeadlineExceeded):
                WriteError(w, http.StatusRequestTimeout, "request timed out")
            default:
                WriteError(w, http.StatusInternalServerError, "server error")
            }
            return
        }

        WriteJSON(w, http.StatusCreated, l)
        return

    default:
        WriteError(w, http.StatusMethodNotAllowed, "method not allowed")
        return
    }
}

func (a *API) linksGet(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    idStr := r.PathValue("id")
    id, err := strconv.Atoi(idStr)
    if err != nil || id <= 0 {
        WriteError(w, http.StatusBadRequest, "invalid link id")
        return
    }

    l, err := a.Links.Get(ctx, id)
    if err != nil {
        switch {
        case errors.Is(err, links.ErrNotFound):
            WriteError(w, http.StatusNotFound, "link not found")
        case errors.Is(err, context.DeadlineExceeded):
            WriteError(w, http.StatusRequestTimeout, "request timed out")
        default:
            WriteError(w, http.StatusInternalServerError, "server error")
        }
        return
    }

    WriteJSON(w, http.StatusOK, l)
}

Step 6: Wire it all together in `cmd/api/main.go`

Create cmd/api/main.go

package main

import (
    "context"
    "errors"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"

    "example.com/paylinks/internal/httpapi"
    "example.com/paylinks/internal/links"
)

func main() {
    logger := log.New(os.Stdout, "", log.LstdFlags)

    apiKey := os.Getenv("API_KEY")
    store := links.NewMemoryStore()
    service := links.NewService(store)

    api := &httpapi.API{Links: service}
    routes := api.Routes()

    handler := httpapi.Chain(
        routes,
        httpapi.RequestID,
        httpapi.Logging(logger),
        httpapi.APIKeyAuth(apiKey),
    )

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           handler,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       10 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    go func() {
        logger.Println("listening on http://localhost:8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            logger.Fatalf("server error: %v", err)
        }
    }()

    waitForShutdown(logger, srv)
}

func waitForShutdown(logger *log.Logger, srv *http.Server) {
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

    <-stop
    logger.Println("shutting down...")

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        logger.Printf("shutdown error: %v", err)
    }
    logger.Println("bye")
}

Run it:

API_KEY=supersecret go run ./cmd/api

Try without auth:

curl -s http://localhost:8080/links

You should get unauthorized.

Try with auth:

curl -s http://localhost:8080/links -H "X-API-Key: supersecret"

Now it works.

This is the exact point where a lot of people tell themselves they have “security”. You do not. You have a locked door. It is still a wooden door. But it is better than a sign that says “please do not hack”.

Step 7: Write tests that prove your routes behave

This is where confidence comes from. Not vibes.

Create internal/httpapi/handlers_test.go

package httpapi

import (
    "bytes"
    "net/http"
    "net/http/httptest"
    "testing"

    "example.com/paylinks/internal/links"
)

func newTestServer() http.Handler {
    store := links.NewMemoryStore()
    service := links.NewService(store)
    api := &API{Links: service}
    return api.Routes()
}

func TestHealth(t *testing.T) {
    h := newTestServer()

    req := httptest.NewRequest(http.MethodGet, "/health", nil)
    rec := httptest.NewRecorder()

    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d", rec.Code)
    }
}

func TestCreateAndGetLink(t *testing.T) {
    h := newTestServer()

    // Create
    body := []byte(`{"amount":5000,"currency":"kes","note":"invoice 183"}`)
    req := httptest.NewRequest(http.MethodPost, "/links", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    rec := httptest.NewRecorder()

    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusCreated {
        t.Fatalf("expected 201, got %d body=%s", rec.Code, rec.Body.String())
    }

    // Get
    req2 := httptest.NewRequest(http.MethodGet, "/links/1", nil)
    rec2 := httptest.NewRecorder()

    h.ServeHTTP(rec2, req2)

    if rec2.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d body=%s", rec2.Code, rec2.Body.String())
    }
}

func TestCreateValidation(t *testing.T) {
    h := newTestServer()

    body := []byte(`{"amount":0,"currency":"usd"}`)
    req := httptest.NewRequest(http.MethodPost, "/links", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    rec := httptest.NewRecorder()

    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusBadRequest {
        t.Fatalf("expected 400, got %d body=%s", rec.Code, rec.Body.String())
    }
}

Run tests:

go test ./...

If it passes, congrats. You now have a codebase that can be changed without praying.

Step 8: Test auth middleware without hating your life

Right now tests call api.Routes() directly, so they bypass middleware.

That is good. You should test handlers and middleware separately.

Create internal/httpapi/middleware_test.go

package httpapi

import (
    "net/http"
    "net/http/httptest"
    "testing"
)

func TestAPIKeyAuth(t *testing.T) {
    final := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
    })

    h := APIKeyAuth("secret")(final)

    // Missing key
    req := httptest.NewRequest(http.MethodGet, "/links", nil)
    rec := httptest.NewRecorder()
    h.ServeHTTP(rec, req)

    if rec.Code != http.StatusUnauthorized {
        t.Fatalf("expected 401, got %d", rec.Code)
    }

    // Correct key
    req2 := httptest.NewRequest(http.MethodGet, "/links", nil)
    req2.Header.Set("X-API-Key", "secret")
    rec2 := httptest.NewRecorder()
    h.ServeHTTP(rec2, req2)

    if rec2.Code != http.StatusOK {
        t.Fatalf("expected 200, got %d", rec2.Code)
    }

    // Health is public
    req3 := httptest.NewRequest(http.MethodGet, "/health", nil)
    rec3 := httptest.NewRecorder()
    h.ServeHTTP(rec3, req3)

    if rec3.Code != http.StatusOK {
        t.Fatalf("expected 200 for health, got %d", rec3.Code)
    }
}

Run:

go test ./...

What we fixed, in human terms

You now have:

Routing that stays clean because handlers are thin
Business rules that live in a service, not scattered around
Middleware that centralizes behavior like auth
Timeouts so requests do not hang forever
Tests that turn fear into evidence

Also, you avoided the classic trap where the router becomes your entire application.

Your router is now just traffic control. As it should be.

Routing in Go Part 1: A small server you can grow without rewriting at midnight

Edgar Nahama Alochi — Sat, 22 Aug 2026 20:30:50 +0000

A small server you can grow without rewriting at midnight

Let me tell you how most “simple” Go servers die.

Day one: you ship a tiny API. One file. Three routes. Clean. You feel like a responsible adult.

Day fourteen: product asks for “just one more endpoint.” You add it.

Day twenty: you add auth. You copy paste auth into every handler because it is faster than thinking. You promise to clean it up later.

Day thirty: you have ten endpoints and three different authentication schemes, all apparently designed on mornings fueled by Cuban coffee, bold, chaotic, and deeply regrettable. Someone reports a bug, you fix it in one handler, and it still pops up because the other handler is running the vintage copy pasted Cuban roast edition.

If this had been built on calm, methodical Kenyan coffee, bright, balanced, and actually consistent, we might have one auth flow and far fewer existential crises

Then you do the most dangerous thing an engineer can do.

You say, “It is fine, it is just a small server.”

That phrase is how small servers become unmaintainable servers. Not because Go is hard. Because routing becomes a junk drawer.

So in this note, we are going to build a Go server with routing that stays boring and predictable. Boring is good. Boring survives.

The case we are building

You run a tiny payments product. Merchants hit your API to create payment links, list them, and fetch one link.

You have these routes:

GET /health so uptime monitors stop emailing you at 3am
POST /links create a payment link
GET /links list payment links
GET /links/{id} fetch one payment link

You are going to do this using the standard library, plus a small amount of structure so you do not end up with spaghetti handlers.

Everything compiles. No hidden magic.

Step 0: Create the project

mkdir go-routing-paylinks
cd go-routing-paylinks
go mod init example.com/paylinks

Create a file called main.go.

Step 1: Start with a server that is not allergic to production

Most examples online start with this:

http.ListenAndServe(":8080", nil)

That is fine for a tutorial. It is also how you end up with timeouts that do not exist and shutdowns that happen by accident.

We are going to start with sane defaults.

Paste this full program first. Run it. Confirm it works. Then we will add routes.

package main

import (
    "context"
    "encoding/json"
    "errors"
    "log"
    "math/rand"
    "net"
    "net/http"
    "os"
    "os/signal"
    "strconv"
    "syscall"
    "time"
)

func main() {
    logger := log.New(os.Stdout, "", log.LstdFlags)

    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    handler := chain(
        mux,
        requestIDMiddleware,
        loggingMiddleware(logger),
    )

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           handler,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       10 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    go func() {
        logger.Println("listening on http://localhost:8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            logger.Fatalf("server error: %v", err)
        }
    }()

    waitForShutdown(logger, srv)
}

func waitForShutdown(logger *log.Logger, srv *http.Server) {
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

    <-stop
    logger.Println("shutting down...")

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        logger.Printf("shutdown error: %v", err)
    }
    logger.Println("bye")
}

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func writeError(w http.ResponseWriter, status int, msg string) {
    writeJSON(w, status, map[string]string{"error": msg})
}

type middleware func(http.Handler) http.Handler

func chain(h http.Handler, m ...middleware) http.Handler {
    for i := len(m) - 1; i >= 0; i-- {
        h = m[i](h)
    }
    return h
}

func requestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" {
            id = newRequestID()
        }
        w.Header().Set("X-Request-Id", id)
        next.ServeHTTP(w, r)
    })
}

func loggingMiddleware(logger *log.Logger) middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)
            logger.Printf("%s %s from=%s dur=%s",
                r.Method,
                r.URL.Path,
                clientIP(r),
                time.Since(start).Round(time.Millisecond),
            )
        })
    }
}

func clientIP(r *http.Request) string {
    host, _, err := net.SplitHostPort(r.RemoteAddr)
    if err != nil {
        return r.RemoteAddr
    }
    return host
}

func newRequestID() string {
    return strconv.FormatInt(time.Now().UnixNano(), 36) + "-" + strconv.Itoa(rand.Intn(1000000))
}

Run it:

go run .

Test it:

curl -s http://localhost:8080/health

If you get {"status":"ok"}, you are alive. The server is alive. Your monitoring tool is calm. Your inbox is safe for now.

Step 2: The pain we are fixing

Here is the most common routing mistake.

You start adding endpoints and you mix routing with business logic in one place. Then you add validation. Then you add auth. Then you add “just a quick special case.” Then it becomes a bowl of logic noodles.

We are going to avoid that by doing something boring:

define our data model
define a store
build handlers that only do HTTP work
keep shared behavior in middleware

This is not “enterprise architecture.” This is “I would like to sleep.”

Step 3: Build the payment link store

We will use an in memory store for the tutorial, but we will write it like it could become a database later.

Add this under the imports in main.go, after the imports.

type PayLink struct {
    ID        int       `json:"id"`
    Amount    int       `json:"amount"`
    Currency  string    `json:"currency"`
    Note      string    `json:"note"`
    CreatedAt time.Time `json:"created_at"`
}

type linkStore struct {
    mu    sync.RWMutex
    next  int
    links map[int]PayLink
}

func newLinkStore() *linkStore {
    return &linkStore{
        next:  1,
        links: make(map[int]PayLink),
    }
}

func (s *linkStore) create(amount int, currency, note string) PayLink {
    s.mu.Lock()
    defer s.mu.Unlock()

    l := PayLink{
        ID:        s.next,
        Amount:    amount,
        Currency:  currency,
        Note:      note,
        CreatedAt: time.Now().UTC(),
    }
    s.links[l.ID] = l
    s.next++
    return l
}

func (s *linkStore) list() []PayLink {
    s.mu.RLock()
    defer s.mu.RUnlock()

    out := make([]PayLink, 0, len(s.links))
    for _, l := range s.links {
        out = append(out, l)
    }
    return out
}

func (s *linkStore) get(id int) (PayLink, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    l, ok := s.links[id]
    return l, ok
}

Important: you need to add sync to your imports.

So your imports should include:

"sync"

Step 4: Add routes that do not turn into a crime scene

Now we wire up handlers.

Modern Go’s ServeMux supports patterns like GET /links/{id} and lets you extract {id} using r.PathValue("id").

Inside main(), add the store:

store := newLinkStore()

Then add these routes after the health route.

mux.HandleFunc("/links", func(w http.ResponseWriter, r *http.Request) {
    switch r.Method {
    case http.MethodGet:
        writeJSON(w, http.StatusOK, store.list())
        return

    case http.MethodPost:
        var body struct {
            Amount   int    `json:"amount"`
            Currency string `json:"currency"`
            Note     string `json:"note"`
        }
        if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
            writeError(w, http.StatusBadRequest, "invalid JSON body")
            return
        }

        body.Currency = strings.ToUpper(strings.TrimSpace(body.Currency))
        body.Note = strings.TrimSpace(body.Note)

        if body.Amount <= 0 {
            writeError(w, http.StatusBadRequest, "amount must be greater than zero")
            return
        }
        if body.Currency == "" {
            writeError(w, http.StatusBadRequest, "currency is required")
            return
        }
        if len(body.Currency) != 3 {
            writeError(w, http.StatusBadRequest, "currency must be a 3 letter code like USD")
            return
        }

        l := store.create(body.Amount, body.Currency, body.Note)
        writeJSON(w, http.StatusCreated, l)
        return

    default:
        writeError(w, http.StatusMethodNotAllowed, "method not allowed")
        return
    }
})

mux.HandleFunc("GET /links/{id}", func(w http.ResponseWriter, r *http.Request) {
    idStr := r.PathValue("id")
    id, err := strconv.Atoi(idStr)
    if err != nil || id <= 0 {
        writeError(w, http.StatusBadRequest, "invalid link id")
        return
    }

    l, ok := store.get(id)
    if !ok {
        writeError(w, http.StatusNotFound, "link not found")
        return
    }

    writeJSON(w, http.StatusOK, l)
})

You will also need to add strings to imports.

So imports should include:

"strings"

At this point you have all the routes you need. But let’s not pretend we are done. We still need the full file to compile.

To keep you from hunting missing imports, here is the full working main.go in one piece.

Full working code

Copy this whole file and run go run .

package main

import (
    "context"
    "encoding/json"
    "errors"
    "log"
    "math/rand"
    "net"
    "net/http"
    "os"
    "os/signal"
    "strconv"
    "strings"
    "sync"
    "syscall"
    "time"
)

type PayLink struct {
    ID        int       `json:"id"`
    Amount    int       `json:"amount"`
    Currency  string    `json:"currency"`
    Note      string    `json:"note"`
    CreatedAt time.Time `json:"created_at"`
}

type linkStore struct {
    mu    sync.RWMutex
    next  int
    links map[int]PayLink
}

func newLinkStore() *linkStore {
    return &linkStore{
        next:  1,
        links: make(map[int]PayLink),
    }
}

func (s *linkStore) create(amount int, currency, note string) PayLink {
    s.mu.Lock()
    defer s.mu.Unlock()

    l := PayLink{
        ID:        s.next,
        Amount:    amount,
        Currency:  currency,
        Note:      note,
        CreatedAt: time.Now().UTC(),
    }
    s.links[l.ID] = l
    s.next++
    return l
}

func (s *linkStore) list() []PayLink {
    s.mu.RLock()
    defer s.mu.RUnlock()

    out := make([]PayLink, 0, len(s.links))
    for _, l := range s.links {
        out = append(out, l)
    }
    return out
}

func (s *linkStore) get(id int) (PayLink, bool) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    l, ok := s.links[id]
    return l, ok
}

func main() {
    logger := log.New(os.Stdout, "", log.LstdFlags)
    store := newLinkStore()

    mux := http.NewServeMux()

    mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
        writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
    })

    mux.HandleFunc("/links", func(w http.ResponseWriter, r *http.Request) {
        switch r.Method {
        case http.MethodGet:
            writeJSON(w, http.StatusOK, store.list())
            return

        case http.MethodPost:
            var body struct {
                Amount   int    `json:"amount"`
                Currency string `json:"currency"`
                Note     string `json:"note"`
            }
            if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
                writeError(w, http.StatusBadRequest, "invalid JSON body")
                return
            }

            body.Currency = strings.ToUpper(strings.TrimSpace(body.Currency))
            body.Note = strings.TrimSpace(body.Note)

            if body.Amount <= 0 {
                writeError(w, http.StatusBadRequest, "amount must be greater than zero")
                return
            }
            if body.Currency == "" {
                writeError(w, http.StatusBadRequest, "currency is required")
                return
            }
            if len(body.Currency) != 3 {
                writeError(w, http.StatusBadRequest, "currency must be a 3 letter code like USD")
                return
            }

            l := store.create(body.Amount, body.Currency, body.Note)
            writeJSON(w, http.StatusCreated, l)
            return

        default:
            writeError(w, http.StatusMethodNotAllowed, "method not allowed")
            return
        }
    })

    mux.HandleFunc("GET /links/{id}", func(w http.ResponseWriter, r *http.Request) {
        idStr := r.PathValue("id")
        id, err := strconv.Atoi(idStr)
        if err != nil || id <= 0 {
            writeError(w, http.StatusBadRequest, "invalid link id")
            return
        }

        l, ok := store.get(id)
        if !ok {
            writeError(w, http.StatusNotFound, "link not found")
            return
        }

        writeJSON(w, http.StatusOK, l)
    })

    handler := chain(
        mux,
        requestIDMiddleware,
        loggingMiddleware(logger),
    )

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           handler,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       10 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    go func() {
        logger.Println("listening on http://localhost:8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            logger.Fatalf("server error: %v", err)
        }
    }()

    waitForShutdown(logger, srv)
}

func waitForShutdown(logger *log.Logger, srv *http.Server) {
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

    <-stop
    logger.Println("shutting down...")

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        logger.Printf("shutdown error: %v", err)
    }
    logger.Println("bye")
}

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func writeError(w http.ResponseWriter, status int, msg string) {
    writeJSON(w, status, map[string]string{"error": msg})
}

type middleware func(http.Handler) http.Handler

func chain(h http.Handler, m ...middleware) http.Handler {
    for i := len(m) - 1; i >= 0; i-- {
        h = m[i](h)
    }
    return h
}

func requestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-Id")
        if id == "" {
            id = newRequestID()
        }
        w.Header().Set("X-Request-Id", id)
        next.ServeHTTP(w, r)
    })
}

func loggingMiddleware(logger *log.Logger) middleware {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            next.ServeHTTP(w, r)
            logger.Printf("%s %s from=%s dur=%s",
                r.Method,
                r.URL.Path,
                clientIP(r),
                time.Since(start).Round(time.Millisecond),
            )
        })
    }
}

func clientIP(r *http.Request) string {
    host, _, err := net.SplitHostPort(r.RemoteAddr)
    if err != nil {
        return r.RemoteAddr
    }
    return host
}

func newRequestID() string {
    return strconv.FormatInt(time.Now().UnixNano(), 36) + "-" + strconv.Itoa(rand.Intn(1000000))
}

Step 5: Test the story, not just the code

Run:

go run .

Create a link:

curl -s -X POST http://localhost:8080/links \
  -H "Content-Type: application/json" \
  -d '{"amount":5000,"currency":"kes","note":"invoice 183"}'

List links:

curl -s http://localhost:8080/links

Fetch one:

curl -s http://localhost:8080/links/1

You now have a small API that demonstrates clean routing, basic validation, a store layer, middleware, and graceful shutdown.

And importantly, you did not create a handler that is half router, half therapist.

Why this structure stays sane

The rule is simple.

Handlers should be boring.

A handler should do three things:

parse and validate input
call a store or service
write a response

Middleware should handle cross cutting behavior like logging, request IDs, and auth.

If you keep that boundary, your routes do not rot. If you blur it, you will eventually spend a Saturday rewriting a server that “was just a small server.”

The Role of Clear Documentation in Team Velocity

Edgar Nahama Alochi — Sat, 01 Aug 2026 06:07:50 +0000

Most teams treat documentation like a speed bump.

They are wrong.

Documentation is engine oil.

When a team says “we don't have time to document,” what they are really saying is:

“We prefer to finance our progress with high-interest technical debt.”

Velocity is not about how fast you can type.

It is about how rarely you stop, stare at a function, and wonder what the developer who wrote it six months ago was trying to accomplish.

Documentation is not paperwork.

It is the preservation of intent.

The Speed Trap

There is a persistent myth in engineering:

“The code is the documentation.”

This is partially true.

Code explains what the system does. It is the ultimate source of truth for implementation.

But code is silent about why it does it that way.

Code tells you the implementation.

Documentation tells you the trade-offs.

When the why disappears, velocity disappears with it.

Every time a new engineer joins the team — or an old engineer returns to a forgotten module — they must perform digital archaeology. They dig through commit history, Slack threads, and half-remembered conversations trying to reconstruct the missing context.

This is not speed.

It is friction disguised as progress.

Why Velocity Actually Stalls

Velocity rarely dies because engineers type slowly.

Velocity dies because of uncertainty.

It shows up in predictable ways.

The Tribal Knowledge Tax

Critical information exists only in the heads of three senior engineers.

To move forward, you must interrupt them.

Your progress comes at the cost of their focus. The team slows down while pretending to move faster.

The Regression Loop

You see a line of code that looks redundant.

You remove it.

Two days later production breaks because that “redundant” line was quietly preventing an edge case discovered during a 2022 incident.

Documentation would have saved you two days and a few grey hairs.

The Decision Re-Run

The team spends three hours debating an architectural decision.

Six months later, the exact same meeting happens again.

No one remembers why the first decision was made.

So the debate starts from zero.

Again.

Documentation shrinks the time-to-understanding.

If a system takes ten minutes to understand instead of two hours, the team does not just move faster.

It moves confidently.

What to Document (And What to Ignore)

Most documentation fails because it documents the wrong things.

It explains syntax instead of decisions.

Useful documentation follows three simple rules.

1. Context Over Syntax

Do not explain that a loop iterates over an array.

Engineers already know that.

Explain why the system uses an array instead of a stream, or why a synchronous call was chosen over an asynchronous one.

The value of documentation is not repeating the code.

It is explaining the reasoning behind it.

2. Record Decisions (ADRs)

Architectural Decision Records are one of the highest leverage tools in engineering teams.

Every significant design decision should answer three questions:

What did we choose?
What alternatives did we consider?
Why did we reject them?

Without this, every new engineer eventually believes they have discovered a brilliant idea.

Often it is simply the same idea the team rejected two years ago.

3. The README Is a Map

A good README should get a new engineer from:

git clone

to a running, tested environment in five minutes.

If onboarding takes an hour, the documentation is broken.

If it takes two days, the architecture probably is too.

The Discipline of the Grown Engineer

Writing good documentation feels like a chore.

That is because it forces clarity.

You can hide confusion inside complicated code.

You cannot hide it inside a clear sentence.

If you cannot explain the intent of your system in writing, there is a good chance you do not fully understand it yet.

Documentation is not busywork.

It is an act of empathy for:

your future self
your teammates
the engineer who will inherit the system three years from now

(Who, statistically speaking, might also be you.)

The Uncomfortable Conclusion

Velocity is a function of clarity.

If your team claims to be moving fast but:

the architecture is a mystery
onboarding feels like a two-week hazing ritual
and every change requires consulting the “one person who knows the system”

then the team is not fast.

It is fragile.

Real velocity is sustainable.

It comes from a shared, written understanding of the system — one that survives beyond any individual developer.

Stop thinking of documentation as extra work.

Documentation is the work.

Everything else is just typing.

Designing for Change, Not Control

Edgar Nahama Alochi — Fri, 31 Jul 2026 17:21:11 +0000

There is a quiet lie we tell ourselves when we design systems.

We call it structure. We call it governance. We call it standards, frameworks, alignment. But beneath all those respectable words is a single desire: control.

I understand the temptation. I have felt it myself. When you are responsible for a system, a product, a team, or an organisation, you want predictability. You want to believe that if you think hard enough and design carefully enough, you can eliminate surprises. You want the future to behave.

It never does.

Architecture, whether technical or organisational, is temporal. A decision that is correct today can become a liability tomorrow. What solves a constraint at one stage often becomes the bottleneck at the next. That is not failure. That is the nature of growth.

The problem begins when we design as though today’s constraints will last forever.

Control is a snapshot. It captures the present and freezes it. But the world is not static. Markets move. Teams change. Customers evolve. Technology ages. Even our own understanding matures. Designing for control assumes stability. Designing for change assumes movement.

And movement is the more honest assumption.

When I design systems now, I do not ask, “How do I make this perfect?” I ask, “How will this need to evolve?” The first question leads to rigidity. The second leads to resilience.

Perfection is brittle. Resilience bends.

There is a particular kind of comfort that comes from tightly coupling everything. When components depend deeply on each other, when processes are heavily standardised, when decisions must pass through a single authority, things appear orderly. It feels safe. But that safety is deceptive. It works beautifully until the first significant change arrives. Then the cost of altering one part ripples through the entire structure.

Loose coupling, on the other hand, can feel untidy. It requires trust. It requires clarity at the boundaries rather than micromanagement at the centre. But when change inevitably comes, the system absorbs it rather than shattering under it.

Designing for change also demands humility. It means admitting that we do not fully understand the future. It means recognising that our current models are provisional. I have seen teams spend months polishing a grand design, only to discover that real users behave in ways no whiteboard session predicted. Feedback is not an interruption to design. It is design.

The deeper lesson is human. Systems do not change themselves. People change them. If the people inside a system do not understand it, cannot question it, or are afraid to adjust it, then no amount of architectural elegance will save it. Real adaptability comes from shared understanding, not from tighter control mechanisms.

There is a difference between clarity and control. Clarity defines purpose, principles, and constraints. Control dictates every action. The former enables autonomy. The latter suffocates it.

When I think about architecture over time, I see phases. Early on, we optimise for speed. Later, we optimise for stability. Eventually, we must optimise for adaptability. The mistake is assuming one optimisation strategy works forever. It does not. Every stage of growth creates new pressures. The structures that enabled momentum in one phase can quietly inhibit it in the next.

The irony is that designing for change often results in calmer systems. When flexibility is built in, emergencies decrease. When experimentation is safe, innovation becomes routine rather than disruptive. When failure is expected and contained, it does not escalate into catastrophe.

Control, by contrast, creates fragility. The tighter we grip, the more dramatic the break when something slips through.

This does not mean abandoning discipline. Designing for change is not the same as chaos. It requires clear interfaces, explicit assumptions, measurable outcomes, and thoughtful boundaries. It demands observability so that when the system shifts, we can see it. It demands modularity so that change in one area does not infect the whole. It demands continuous reflection so that decisions are revisited rather than fossilised.

In practice, this means making decisions that are reversible where possible. It means favouring principles over prescriptions. It means documenting intent, not just implementation. It means building teams capable of evolving the system rather than depending on a single architect to guard it.

Most importantly, it means letting go of the illusion that control equals competence.

Competence is the ability to adapt.

When I look back at systems I am proud of, they share a common trait. They survived change. They were not flawless. They were not static. They evolved without collapsing. The decisions within them were not perfect, but they were adjustable.

That is the standard I aim for now. Not control, but capacity. Not rigidity, but resilience. Not permanence, but progression.

The tide will always come in. The only real question is whether what we have built can endure its arrival and reshape itself when it does.

Design for that.

How to write technical posts that survive AI noise

Edgar Nahama Alochi — Wed, 29 Jul 2026 23:08:29 +0000

There is a new kind of content pollution on the internet.

It is clean looking.
It is fast.
It is confident.
It is usually correct in the same way instant noodles are usually a meal.

You have seen it.

Twenty posts explaining distributed systems with suspiciously identical examples.
Thirty threads about performance that all end with the same advice about caching.
A flood of technical content that sounds useful until you try to build anything from it and realize you were given a polished summary of someone else’s summary of someone else’s blog post from 2018.

This is the AI noise era.

Which is not the same thing as saying AI is bad.
It is not.
It is useful.
It is fast.
It can help good writers think better and move faster.

But it has changed the publishing environment in one important way.

Average content is now almost free.

That means the old strategy of writing a technically correct post with generic advice is no longer enough. If your post can be recreated in six seconds by a prompt and a decent model, your post is competing in a commodity market. Commodity markets are not kind to authors.

So the question is not how to write more posts.

The question is how to write technical posts that still matter when everyone can publish instantly.

The answer is depth.
But not the fake kind.

Real depth.

The kind that comes from contact with reality.

The first rule is simple

Write from experience before you write from explanation.

Most technical posts fail because they start with the concept and never arrive at the problem.

They explain what a thing is.
They list benefits.
They define terms.
They sound educational.
They leave the reader unchanged.

People do not remember definitions.
They remember tension.

A post survives AI noise when it begins with something the model cannot fake well on its own.
A real incident.
A painful trade off.
A mistake that cost time.
A decision that looked smart and later failed in production.
A problem that refused to behave the way the docs promised.

This does not mean every post needs a war story.

It means every post needs friction.

If you are writing about retries, do not begin with a textbook explanation of retries.

Begin with the duplicate payout incident.
Begin with the customer who got charged twice.
Begin with the queue that politely melted your downstream service because you retried immediately and at scale.
Now the reader cares.

AI can summarize concepts.
It struggles to replace earned judgment.

That is your advantage.
Use it.

Write for people who have to make decisions

A lot of technical writing is written for imaginary readers who have infinite time, full context, and no budget pressure.

That reader does not exist.

Real readers are trying to decide something.

Should we adopt this tool.
Should we refactor this service.
Should we split the database.
Should we introduce a queue.
Should we keep the monolith another year.
Should we trust this benchmark.
Should we hire for this skill.

If your post does not help someone make a decision, it will be skimmed, bookmarked, and forgotten. Which is a very polite way of saying ignored forever.

Strong technical posts are decision support documents disguised as articles.

They help the reader answer questions like these.

What problem is this actually good at solving.
What does it cost to run in the real world.
What breaks first.
What team maturity is required.
What signs tell me I am too early.
What signs tell me I am already late.

This is where experience shows.

A junior writer often explains what is possible.
A seasoned writer explains what is advisable.

That second one survives.

Stop writing encyclopedias

One of the easiest ways to sound intelligent and be useless is to write the complete guide.

The complete guide is often just a long apology for not making choices.

It includes everything.
It excludes judgment.
It is impossible to disagree with because it refuses to commit.

In an AI heavy internet, completeness is no longer a moat.
Machines are very good at exhaustive overviews.

What they are worse at is useful reduction.

Readers do not need more information.
They need better compression.

Write narrower.
Cut harder.
Choose a point of view.

Not this.

This article explains everything about observability.

Write this.

If your team has fewer than ten engineers, start observability with latency, error rate, and one business metric before buying a dashboard that requires its own onboarding ceremony.

That sentence has blood pressure.
It has a user.
It has constraints.
It has a recommendation.
Someone can disagree with it.
Good.
Now you are writing.

A post that survives AI noise usually has a spine.
It stands for something.

Originality is not being weird

Many people hear originality and immediately produce chaos.

No.
That is not originality.
That is just caffeine with formatting.

Original technical writing is usually familiar truth described with sharper honesty.

You do not need a revolutionary theory.
You need a real observation stated clearly.

For example.

Most teams do not have a scaling problem. They have a coordination problem wearing a scaling costume.

That is not a new law of physics.
But it is useful.
It is pointed.
It reflects reality many engineers have seen and few say out loud.

Originality often comes from pattern recognition.

After enough years, you notice that the same failure keeps returning in different clothes.
Different stack.
Same mistake.
Different logo.
Same organizational issue.
Different tooling.
Same missing ownership.

Write that pattern down.

That is the work.

AI can recombine language.
It cannot easily replace years of noticing.

Be specific where it matters and abstract where it helps

This is a craft skill and it changes everything.

Weak technical posts stay abstract for too long.
Strong ones move between concrete detail and general principle at the right moments.

If you stay abstract, the post feels airy.
If you stay too concrete, the post becomes a diary entry no one else can use.

You want both.

Show the concrete case.
Then extract the principle.
Then show where the principle breaks.

Example rhythm.

We moved retries into the worker and accidentally multiplied load during provider degradation.

The principle is that resilience mechanisms can increase failure pressure if they are not bounded.

The practical fix was backoff, jitter, idempotency keys, and a hard retry budget tied to business value.

Now the reader gets story, lesson, and implementation direction in one pass.

That survives because it teaches more than facts.
It teaches thinking.

Explain trade offs like an adult

AI generated technical content often has a familiar smell.
Everything is beneficial.
Every tool is powerful.
Every pattern improves scalability, reliability, developer experience, and perhaps your posture.

Real systems do not work like that.

Every technical decision creates winners and losers.
Every abstraction moves complexity somewhere.
Every convenience has a bill.
Usually monthly.

If you want your writing to survive, be the person who names the bill.

Do not just say event driven systems improve decoupling.

Say they also make debugging harder, make data consistency more social than technical, and require teams to care about contracts long after the launch excitement is gone.

Do not just say microservices improve scalability.

Say they can improve scaling for parts of the system while making ownership, testing, and incident response dramatically worse if your team structure is still operating like one monolith with more meetings.

This is what mature readers trust.

Not optimism.
Calibration.

A good technical post should feel like advice from someone who has paid for at least one bad decision.

Add the things AI usually leaves out

If you compare a lot of human technical writing with AI generated writing, one pattern appears quickly.

The machine often covers the what and the why.
It is much weaker on the when, the if, and the what happens next.

That gap is where your writing can become durable.

Include timing.

When should a team adopt this.
What stage is too early.
What symptoms suggest readiness.

Include prerequisites.

What must already be true for this approach to work.
Team skills.
Operational maturity.
Traffic patterns.
Business constraints.

Include failure modes.

How this goes wrong in practice.
What people underestimate.
What breaks during incidents.
What gets expensive quietly.

Include maintenance reality.

Who owns it in month nine.
How upgrades happen.
What knowledge becomes concentrated in one person and ruins everyone’s weekend when that person is offline.

Include reversibility.

Can the team back out.
How expensive is rollback.
What decisions become sticky.

These are not decorative details.
They are the difference between technical writing and technical marketing.

Your readers know the difference, even if they cannot always explain why one felt more trustworthy.

Use examples that reveal judgment, not just syntax

Code examples are good.
Tiny toy snippets with no context are often not.

There is a place for syntax teaching, but if the goal is a post that survives noise, examples should do more than compile.

They should expose design choices.

Instead of showing only how to implement a retry loop, show why you capped retries at a low number for non critical operations and used a dead letter queue for the rest.

Instead of showing only a cache wrapper, show how stale data tolerance changes by domain.
A product catalog can tolerate minutes.
A wallet balance cannot.
Now the reader learns architecture, not just code.

The most valuable examples are the ones that answer the hidden question in every engineer’s mind.

Yes, but how would you do this in a system that people actually use.

Write for that question.

Make your writing falsifiable

This sounds academic.
It is actually practical.

A lot of forgettable content survives only because it says nothing testable.
It is all vibes and verbs.

Robust technical writing makes claims that can be challenged.

For small teams, adding a service mesh before basic observability usually increases operational complexity faster than it increases reliability.

That is a claim.
People can debate it.
People can test it against experience.
People can add nuance.
That is healthy.

When your writing can be disagreed with, it has shape.
When it has shape, it gets remembered.

Do not hide behind endless caveats.
Yes, context matters.
It always matters.
You still have to say something.

The job is not to be impossible to criticize.
The job is to be useful enough to risk criticism.

Write like a human who has met other humans

There is a strange trend in technical writing where people remove all personality in order to sound serious.

This usually produces text that sounds like a compliance document explaining a toaster.

You do not need stand up comedy.
You do need a voice.

Humour helps because it compresses shared pain.

Everyone who has maintained a legacy system understands a line like this.

The code worked perfectly until we looked at it.

That line does work.
It creates rapport.
It signals experience.
It gives the reader a reason to continue.

Sarcasm helps too, in controlled doses.
The keyword is controlled.
You are seasoning a meal, not setting the kitchen on fire.

The goal is not to perform personality.
The goal is to sound like a competent person thinking clearly in public.

That tone survives because readers can feel the difference between a writer and a generator.

Structure matters more now than before

AI noise has trained readers to scan aggressively.

They are not rude.
They are adapting.

If your post has no shape, they will leave before your best point appears.

Give the reader a path.

Open with tension.
Name the problem.
State the claim.
Walk through reasoning.
Show examples.
Acknowledge trade offs.
End with a practical takeaway.

Good structure is not decoration.
It is respect.

It tells the reader you did the sorting before asking for their time.

A useful test is this.

If someone reads only your headings and first sentence of each section, do they still learn something meaningful.

If not, the post may be full of words and low on signal.

The strongest moat is lived specificity

There is a type of detail that instantly increases trust.

Not random detail.
Relevant detail.

We discovered the issue because checkout success rate dropped while API error rate looked normal, which meant the failure was happening in a dependency path our alerting did not treat as critical.

That sentence tells me the writer has been inside a real system.

It tells me they measure the right things.
It tells me they noticed a mismatch.
It tells me the lesson came from operations, not just reading.

This kind of specificity is hard to mass produce at scale.
Which is exactly why it works.

If you want durable writing, keep a notebook of incidents, decisions, and mistakes.
Not just outcomes.
Context too.

What you believed at the time.
What data you had.
What pressure existed.
What trade off you accepted.
What changed your mind.

That notebook becomes future articles.
More importantly, it becomes evidence.

Evidence beats volume.

Do not fight AI by pretending it does not exist

The winning move is not purity.
It is leverage.

Use AI for roughing out outlines.
Use it to challenge your blind spots.
Use it to generate counterarguments.
Use it to find gaps in your explanation.
Use it to clean phrasing after the thinking is done.

But do not outsource judgment.

If the model writes the core argument and you lightly edit it, you may publish faster.
You will also sound like everyone else publishing faster.

The right workflow for technical writing now is something like this.

Think from experience.
Draft from judgment.
Use tools for refinement.
Return with taste.
Cut aggressively.
Add reality.
Publish.

AI can increase your speed.
Only you can increase your signal.

A practical checklist before you publish

Read your draft and ask these questions.

Is there a real problem in the opening or did I start with generic explanation

Have I made at least one clear claim that someone could disagree with

Did I include trade offs or only benefits

Did I write for a decision maker or for an imaginary student of everything

Is there a section that could only come from direct experience

Did I include timing, prerequisites, and failure modes

Did I reduce the scope enough to be useful

Does the post sound like me or like a very polite documentation bot

If the answer to the last one hurts a little, good.
That means the test is working.

Final thought

AI noise is not the end of technical writing.

It is the end of lazy technical writing getting rewarded for existing.

Which is honestly fair.

The bar is different now.
Higher in some ways.
Better in others.

If average content is free, then judgment becomes premium.
If summaries are instant, then lived insight becomes scarce.
If everyone can publish, then the people who last will be the ones who can still say something real.

Write the post only you can write.

Not because it is precious.
Because it is useful.

And useful is still very hard to automate.

The Weekend Gold Rush and the Graveyard It Leaves Behind

Edgar Nahama Alochi — Wed, 29 Jul 2026 04:20:32 +0000

I have seen this movie before. Several times. The actors change. The soundtrack improves. The promises get louder. The ending stays the same.

Around 2000 it was this.

Everyone needs a website. Learn HTML in a weekend.

Suddenly the internet was full of blinking text, broken navigation, tables inside tables inside more tables, and a mysterious visitor counter at the bottom proudly displaying the number 7. Most of those sites died quietly. Some are still out there, fossilized in forgotten hosting accounts, whispering in Comic Sans.

Then 2008 arrived.

Mobile apps are printing money. Just learn iOS development.

Every developer with a MacBook became a visionary founder. To do lists. Flashlight apps. Another to do list but this one is social. The App Store filled up. So did the graveyard. Turns out shipping version one is easy. Maintaining version twelve while Apple changes everything and users demand perfection is not.

Then 2015.

Blockchain will change everything. Smart contracts. Decentralize the world.

Whitepapers were written. Tokens were minted. Conferences were attended. Most projects never launched. Many quietly shut down. The few that survived did so not because of hype, but because someone somewhere treated it like real engineering instead of a lottery ticket.

Now it is 2024.

AI will replace developers. Build a GPT wrapper this weekend. Launch an AI SaaS by Sunday. Retire by Wednesday.

Result?

Still loading.

The pattern is so predictable it should come with documentation.

First, a new technology emerges. It is genuinely powerful. It solves something real. It unlocks new capability.

Early adopters see opportunity. They experiment. They struggle. They learn the sharp edges. They build things that actually work.

Then the get rich quick crowd floods in.

Tutorials appear. Build X in 30 minutes. Ship your AI startup in a day. Passive income while you sleep.

Reality, as it always does, shows up uninvited.

Infrastructure costs are not passive. Hallucinations are not a feature. Latency is not just a vibe. Security matters. Data privacy matters. Customers do not care that you used the latest model if their invoice is wrong.

Then 90 percent fail. Not because the technology was useless. Because they skipped the fundamentals.

This is the part that is boring and therefore ignored.

What actually succeeds is deeply unfashionable.

People who understand the technology, not just the API.

People who solve a real problem instead of wrapping a model around a landing page.

People who build maintainable systems that survive version two.

People who think about cost before the first viral tweet.

People who apply engineering principles that worked before the hype cycle and will work long after it.

Clean architecture still matters.

Proper error handling still matters.

Cost management matters even more when your variable expense is a model that charges per token.

Security matters when your system is literally generating output from user input.

Testing matters. Monitoring matters. Observability matters. Especially when the output is probabilistic and your users expect determinism.

And perhaps most controversial of all, talking to customers still matters.

You cannot prompt engineer your way out of building something nobody wants.

I am not saying AI is not transformative. It is. It changes what is possible. It changes how we work. It changes the leverage a small team can have.

What it does not change is the physics of building durable systems.

After twenty years of watching waves come and go, here is the lesson.

New technology does not obsolete good engineering.

It makes it more important.

Because when the barrier to building drops, the barrier to competing drops with it. When anyone can launch in a weekend, the only thing that differentiates you is depth. Discipline. Taste. Restraint.

The gold rush is always loud.

The people who last are usually quiet.

So the question is simple.

Are you building for the long term.

Or are you building for the demo.

Chaos engineering essentials for small teams

Edgar Nahama Alochi — Tue, 28 Jul 2026 05:58:19 +0000

You do not need Netflix scale to deserve failure

Chaos engineering sounds like something only companies with thousands of microservices and a platform team the size of a small country should care about.

That is a myth.

Small teams break in quieter ways.

A background job silently retries forever.
A webhook endpoint times out and no one notices.
A database connection pool saturates under a traffic spike.
An external payment provider starts returning 502 and your system politely collapses.

Chaos engineering is not about drama.
It is about humility.

It is the discipline of admitting your system will fail and choosing to learn that on a Tuesday afternoon instead of during your biggest customer demo.

What chaos engineering actually is

It is not random destruction.
It is not breaking production for fun.
It is not deleting databases to prove you are brave.

Chaos engineering is controlled failure experimentation.

You form a hypothesis about how your system behaves under stress.
You introduce a small, reversible failure.
You observe.
You learn.
You improve.

That is it.

The goal is confidence.
Not coverage.
Not hero stories.
Confidence.

Why small teams need it more than big ones

Large companies have redundancy in people.

You probably do not.

If one senior engineer is on vacation and the system degrades in a weird way, you do not have a war room. You have Slack messages and mild panic.

Small teams usually have:

Limited observability.
Shared infrastructure.
One database doing everything.
A few critical integrations that must work.
Very little operational slack.

This is exactly the environment where hidden failure modes thrive.

Chaos engineering for small teams is less about sophistication and more about survival.

Essential principle one: start with failure modes, not tools

Before you install anything, answer this question.

How does this system actually die?

Not in theory.
In reality.

Make a simple list.

What happens if the database becomes slow.
What happens if Redis disappears.
What happens if Stripe times out.
What happens if DNS resolution fails.
What happens if one pod runs out of memory.
What happens if a background worker crashes mid job.

If you cannot answer these confidently, you have your starting point.

Chaos begins with thoughtfulness.

Essential principle two: write a steady state definition

You cannot detect degradation if you do not define normal.

What does healthy mean for your system?

It might be:

Ninety nine percent of requests complete under 300 milliseconds.
Error rate stays under one percent.
Checkout success rate stays above a defined threshold.
Background jobs do not accumulate beyond a certain depth.

Write this down.

Chaos engineering without a steady state definition is just creative vandalism.

Essential principle three: start small and reversible

You do not need a chaos platform.
You need discipline.

Examples a small team can run safely:

Introduce artificial latency in a single dependency.
Temporarily block outbound traffic to one third party service.
Kill one application instance.
Throttle CPU on a staging node.
Simulate a failed webhook response.

Do this in staging first.
Then do it in production with tight scope and clear rollback.

If your heart rate is too high while running the experiment, it is too large.

Essential principle four: observability is not optional

If you cannot see it, you cannot learn from it.

At minimum you need:

Request latency metrics.
Error rate metrics.
Basic logs with correlation IDs.
Health indicators for external dependencies.
Alerting tied to real user impact, not infrastructure noise.

Many small teams think they are not ready for chaos engineering.

In reality they are not ready for ignorance.

Even basic metrics change everything.

Essential principle five: automate the lessons

The point of running experiments is not to feel clever.

It is to harden the system.

After every experiment ask:

Did our alerts trigger.
Did we detect the issue quickly.
Did the system degrade gracefully.
Did users notice.
Did recovery require manual heroics.

If the answer includes the word hero, you have work to do.

Add timeouts.
Add circuit breakers.
Add retries with backoff.
Add idempotency.
Add clearer alerts.
Add runbooks.

Small teams win by building systems that fail predictably.

Essential principle six: design for graceful degradation

Perfection is unrealistic.
Grace is achievable.

If a recommendation service fails, the product page should still load.
If an analytics endpoint times out, the checkout must still complete.
If one payment provider fails, another should take over.
If email delivery fails, the core transaction should still succeed.

This is architectural thinking.
Chaos engineering simply reveals where you forgot it.

Essential principle seven: avoid chaos theater

There is a trap here.

You can make chaos engineering look impressive.

Fancy dashboards.
Dramatic experiments.
Big internal presentations.

None of that matters if your system still collapses under simple pressure.

For small teams, chaos engineering should feel boring.

Routine.
Predictable.
Methodical.

If it feels theatrical, you are optimizing for attention.

A practical starter plan for small teams

Here is a calm, realistic roadmap.

Month one.
Define steady state.
Add missing metrics.
Identify top five failure modes.

Month two.
Run one controlled experiment in staging.
Improve alerts and logging.
Document findings.

Month three.
Run one small scoped production experiment.
Fix the weakest resilience gap discovered.
Write a runbook.

Repeat quarterly.

You do not need to be aggressive.
You need to be consistent.

The uncomfortable truth

Your system is already chaotic.

You just have not observed it under stress yet.

Hardware fails.
Networks partition.
Cloud providers degrade.
External APIs rate limit.
Human operators make mistakes.

Chaos engineering is not introducing instability.

It is introducing honesty.

Final thought

Small teams often optimize for speed.

Ship fast.
Fix later.
Trust that things will hold.

Chaos engineering is how you ship fast without gambling.

It gives you confidence that when reality pushes back, your system bends instead of shatters.

You do not need scale to practice resilience.

You need maturity.

And maturity begins with the courage to ask one simple question.

What happens if this breaks.

Then actually finding out.

When to refactor vs rewrite

Edgar Nahama Alochi — Mon, 27 Jul 2026 19:56:55 +0000

A decision tree for grown engineers

Every engineering team eventually faces the same dramatic sentence.

We should just rewrite this.

It is usually said after a bug, a missed deadline, or a moment of emotional exhaustion while reading a file that appears to have been written during a power outage.

Rewriting feels clean. Refactoring feels responsible.

One sounds heroic. The other sounds like laundry.

But this decision is not about emotion. It is about risk, economics, and time.

Let us walk through it like adults.

First question

Does the system work

Not beautifully. Not elegantly. Not in a way that makes you proud.

Does it work.

If the system is stable, generating value, and customers depend on it daily, you are not staring at a technical problem. You are staring at a revenue engine.

Rewriting revenue engines is not bravery. It is surgery.

Refactor when the system works but hurts.

Rewrite when the system fundamentally cannot meet current or future requirements.

If it works and you just dislike the style, close the tab and drink water.

Second question

Is the problem structural or local

Local problems are ugly functions, confusing modules, long files, poor naming, duplicated logic.

Structural problems are incorrect domain models, broken abstractions, wrong architectural boundaries, impossible scaling constraints.

Refactoring fixes local problems very well.

Rewriting is justified only when the architecture itself prevents progress.

If you can improve it piece by piece without stopping delivery, refactor.

If every small change creates chaos because the foundations are wrong, then you may need a rewrite.

Be honest here. Most problems are local.

Third question

Do you fully understand the current system

This is where most rewrite projects quietly die.

If the current system is confusing, that confusion often contains business rules that no one documented.

Legacy code is frequently a fossil record of production incidents.

When you rewrite without fully understanding the behavior, you do not create a cleaner system. You create a regression generator.

If the answer is no, you do not understand it deeply, your first step is not rewrite.

Your first step is to learn.

Refactor while learning. Add tests. Document behavior. Shrink uncertainty.

Rewrite only after you can explain the old system clearly to someone else.

Fourth question

Is delivery allowed to slow down

Rewrites consume focus. They create parallel universes. You maintain old and new simultaneously.

If your company cannot afford slower feature delivery for months, rewriting is fantasy.

Refactoring allows incremental progress. You improve while shipping.

If the business needs momentum, refactor.

If the business is intentionally investing in a platform reset, and everyone understands the cost, then rewrite can be strategic.

But it must be a business decision, not a developer mood swing.

Fifth question

Are tests strong enough to protect you

Refactoring relies on safety nets.

If you do not have meaningful tests, refactoring feels dangerous and rewriting feels tempting.

But here is the uncomfortable truth.

Rewriting without tests is gambling at a higher table.

If you cannot confidently change the system today, you will not magically become confident rebuilding it from scratch.

Invest in tests first.

The decision becomes clearer once safety exists.

Sixth question

Is the pain growing or stable

Some code is ugly but stable. It does its job quietly.

Other systems become slower, harder to change, and more fragile every quarter.

If the cost of change is compounding, you are facing architectural debt.

In that case, continuing to patch may be more expensive than starting fresh.

If the cost is flat and predictable, refactoring over time is usually sufficient.

Measure change cost. Do not guess.

The practical decision tree

Here is the simplified version.

Does it work and generate value
Yes
Then prefer refactor

Does the architecture block critical future goals
Yes
Consider rewrite

Do you deeply understand current behavior
No
Learn and refactor first

Can the business tolerate slower delivery
No
Refactor

Are tests strong
No
Strengthen them before anything dramatic

Is change cost compounding
Yes
Rewrite might be strategic

Notice something.

Rewrite appears only after several gates.

That is intentional.

The emotional trap

Rewriting feels productive because it removes friction instantly.

You open a new folder. The files are clean. The abstractions are pure. You feel like an architect instead of a mechanic.

But software is not a painting. It is an evolving system embedded in reality.

The old code survived production traffic. It contains scar tissue that protects you from repeating mistakes.

Refactoring respects that history.

Rewriting erases it.

Sometimes erasing is necessary. Often it is ego.

A healthier pattern

Instead of thinking refactor or rewrite, think in layers.

Stabilize the existing system with tests.

Extract boundaries slowly.

Replace modules behind interfaces.

Strangle old components with new ones.

Over time, the system becomes new without a dramatic rewrite event.

The business never feels a reset. The engineers never freeze progress.

This is less cinematic. It is also less catastrophic.

The uncomfortable conclusion

Most teams do not need rewrites.

They need discipline.

They need tests, clearer boundaries, smaller pull requests, and patience.

Rewrites are rare strategic moves.

Refactoring is daily engineering.

If you find yourself wanting to rewrite, ask one final question.

Am I solving a structural constraint
Or am I trying to escape complexity I have not yet understood

The answer determines whether you are being an engineer

Or just emotionally refactoring your feelings.

NASA's Rule of 10: The rules of programing that put flying metal in orbit

Edgar Nahama Alochi — Sun, 26 Jul 2026 14:00:28 +0000

The NASA Ten Rules of Programming

My interpretation of these rules with Golang examples.

NASA did not write these rules to win arguments on the internet.
They wrote them because software failed in ways that were expensive frightening and sometimes irreversible.

The rules are short. Almost annoyingly so.
That is intentional.

Each rule is a reminder that complexity is not free and that computers are fast but humans are fragile.

They helped put flying metals in orbit and manage Voyager 1, the most distant human made object.

Let’s walk through all ten using Go not because Go is perfect but because it makes these ideas painfully obvious.

Rule 1

Restrict all code to very simple control flow

If your logic requires a mental stack trace to understand it will fail at the worst possible moment.

Go helps here by being boring on purpose.

Bad

func process(x int) int {
    if x > 0 {
        for x < 100 {
            if x%2 == 0 {
                if x%3 == 0 {
                    x += 7
                } else {
                    x += 3
                }
            } else {
                break
            }
        }
    }
    return x
}

Good

func process(x int) int {
    if x <= 0 {
        return x
    }

    for x < 100 {
        if x%2 != 0 {
            return x
        }
        x = nextValue(x)
    }

    return x
}

func nextValue(x int) int {
    if x%3 == 0 {
        return x + 7
    }
    return x + 3
}

Simple flow is not about fewer lines.
It is about fewer thoughts.

Rule 2

Give all loops a fixed upper bound

Unbounded loops are promises you cannot keep.

They say trust me this will eventually stop.
NASA does not trust that. Neither should you.

Bad

for {
    data := read()
    if data == nil {
        break
    }
    process(data)
}

Better

for i := 0; i < maxReads; i++ {
    data := read()
    if data == nil {
        return
    }
    process(data)
}

Even when reading streams you can still impose limits.
Timeouts retries counters budgets.

Infinite loops belong in theory not production.

Rule 3

Avoid heap memory allocation after initialization

This rule scares people because it sounds extreme.

What it really says is do not allocate memory unpredictably while running critical logic.

In Go you do not control the heap but you can control when and how you allocate.

Bad

func handle(req Request) {
    buf := make([]byte, req.Size)
    process(buf)
}

Better

type Handler struct {
    buf []byte
}

func NewHandler(maxSize int) *Handler {
    return &Handler{
        buf: make([]byte, maxSize),
    }
}

func (h *Handler) Handle(req Request) {
    process(h.buf[:req.Size])
}

This is not about micro optimization.
It is about predictability.

The garbage collector is helpful.
It is not magic.

Rule 4

Restrict functions to a single purpose

If a function does more than one thing it lies about its name.

Bad

func SaveUser(u User) error {
    validate(u)
    db.Save(u)
    log.Printf("saved user %s", u.ID)
    sendEmail(u)
    return nil
}

Better

func SaveUser(u User) error {
    if err := validate(u); err != nil {
        return err
    }
    return db.Save(u)
}

Side effects should be explicit and separate.

Small functions fail smaller.

Rule 5

Use a minimum of two runtime assertions per function

This rule is about defending assumptions.

In Go assertions usually look like early checks.

Bad

func divide(a b int) int {
    return a / b
}

Better

func divide(a b int) (int error) {
    if b == 0 {
        return 0 errors.New("division by zero")
    }
    return a / b nil
}

Assertions are kindness to future readers.
Especially future you at 2am.

Rule 6

Declare data objects at the smallest possible scope

The longer a variable lives the more places it can hurt you.

Bad

var result int

func compute(a b int) int {
    result = a + b
    return result
}

Better

func compute(a b int) int {
    result := a + b
    return result
}

Short lifetimes mean fewer ghosts in the system.

Rule 7

Check the return value of all non void functions

This is the rule Go takes personally.

Ignoring errors is lying to yourself.

Bad

file _ := os.Open("data.txt")

Better

file err := os.Open("data.txt")
if err != nil {
    return err
}

Errors are information.
Discarding them does not make them go away.

Rule 8

Limit pointer use

Pointers increase the number of possible states your program can be in.

Go uses pointers but discourages pointer gymnastics.

Bad

func update(u *User) {
    u.Name = strings.ToUpper(u.Name)
}

Better

func update(u User) User {
    u.Name = strings.ToUpper(u.Name)
    return u
}

Use pointers when you must not because you can.

Rule 9

Compile with all warnings enabled and treat them as errors

Go does not have warnings.
It simply refuses to compile nonsense.

Unused variables unused imports unreachable code.
All dead on arrival.

That is a feature not a limitation.

If your language allows warnings treat them like failures.
Your future stability depends on it.

Rule 10

Use static analysis tools

Humans miss patterns.
Machines do not get tired.

In Go this means tools like

go vet
staticcheck
race detector

Example

go test -race ./...

These tools are not optional extras.
They are part of the engineering system.

NASA trusted them with spacecraft.
You can trust them with your backend.

The quiet lesson behind the rules

The NASA rules are not about cleverness.
They are about humility.

They assume that you will forget.
That you will misread.
That you will be interrupted.

They are written for humans under pressure.

Go as a language aligns with this philosophy almost accidentally.
Simple syntax explicit errors limited abstraction boring defaults.

The rules remind us that reliability is not achieved by brilliance.
It is achieved by restraint.

And restraint scales better than genius ever will.

A Small, Annoying Reminder About MySQL, Next.js, and Reality

Edgar Nahama Alochi — Sat, 25 Jul 2026 20:01:24 +0000

Today's reminder that MySQL will happily let you believe you're doing everything "right" right up until it doesn't.

I was wiring up a perfectly ordinary paginated query in a Next.js service. Nothing exotic. Prepared statements, placeholders, clean parameter handling. The kind of code you write on autopilot because you've written it a hundred times before.

And then MySQL reminded me again that it is not PostgreSQL.

The offending query looked harmless:

SELECT *
FROM writings
ORDER BY created_at DESC
LIMIT ? OFFSET ?

The parameters were validated. Integers only. Floored. Bounded. Safe. Sensible.

And still: runtime error.

The cause, as always, is not obvious until you already know it:

MySQL does not support placeholders forLIMIT and OFFSET in prepared statements.

Not partially. Not "sometimes." Just no.

This is one of those behaviors that lives in the uncanny valley between "documented" and "constantly forgotten." Every time I switch contexts PostgreSQL to MySQL, ORM generated queries to raw SQL I relearn this the hard way.

The fix is simple, but mildly infuriating.

Instead of placeholders, you must interpolate the integers directly:

const limitInt = Math.floor(limitNum);
const offsetInt = Math.floor(offset);

const dataQuery = `
  SELECT *
  FROM writings
  ${whereClause}
  ORDER BY created_at DESC
  LIMIT ${limitInt} OFFSET ${offsetInt}
`;

And yes, this is safe because:

limitNum andoffsetare validated
Values are clamped and floored
They cannot contain user controlled strings
Only WHERE clause values remain parameterized

The resulting query is exactly what MySQL expects:

text

SELECT *
FROM writings
ORDER BY created_at DESC
LIMIT 6 OFFSET 0

Instead of the version MySQL silently refuses to support:

SELECT *
FROM writings
ORDER BY created_at DESC
LIMIT ? OFFSET ?

This is not a Next.js problem.
It is not a driver bug.
It is not a configuration issue.

It is simply one of those MySQL constraints that leaks through abstraction layers and reminds you that SQL dialects are not interchangeable, no matter how much tooling tries to pretend they are.

The frustrating part isn't the workaround.
The frustrating part is that this failure happens after you've already done the "right" things:

Prepared statements
Parameterized queries
Defensive validation
Boring, careful code

And yet, you still have to break the pattern carefully, deliberately to satisfy the database.

The takeaway is not "don't use MySQL."
The takeaway is simpler, and more annoying:

Always remember which database you are talking to.

Because the moment you assume uniform behavior across SQL engines, reality will correct you usually in production.

Fixed.
Again.

Understanding Next.js Page Caching (with a real example)

Edgar Nahama Alochi — Wed, 22 Jul 2026 23:12:10 +0000

Caching can be a tricky topic, especially when pages don’t update the way you expect.
I recently ran into an interesting issue while working on the /writing page of my site. Whenever I added or updated articles, the changes did not show immediately. Oddly enough, the individual article pages updated as expected, but the listing page stayed stale.

After some digging, I realized this was not a bug. It was Next.js doing exactly what it is supposed to.

How Next.js caching works

Next.js (App Router) handles HTML caching at the edge in production. For statically prerendered pages, it sets Cache-Control: s-maxage=31536000, which is one year. This header tells CDNs and edge caches that they can serve the page without re-fetching for a long time. Browser cache headers such as no-cache do not override this because s-maxage takes priority for shared caches.

This explains why the listing page showed stale content while individual article pages, which are either dynamic or use revalidation, updated immediately.

How to control caching

Next.js provides a clean way to manage page freshness.

First, set revalidation for a page. In the page file, for example app/writing/page.tsx, add:

export const revalidate = 60; // seconds

The page is served from cache for 60 seconds. After 60 seconds, the next visitor triggers background regeneration. Visitors continue to get a fast response while the page updates.

For instant updates after saving content, use on-demand revalidation:

import { revalidatePath } from 'next/cache';
revalidatePath('/writing');

Call this in your article save logic, whether that is a CMS, API route, or webhook, to invalidate the cached page immediately.

Key lessons from my experience

Edge caching is powerful, but it can make pages seem stale if revalidation is not configured. Browser cache clearing or changing Nginx headers does not affect HTML caching for statically prerendered pages. The correct place to control page freshness is in the Next.js route itself, not the server or CDN alone.

By adding a single line of code to the route, I now get the perfect balance: fast cached pages that still update reliably when I add or edit content.

References

Next.js ISR and Self-hosting

Next.js Caching and Revalidation

Next.js Config and Headers

DEV Community: Edgar Nahama Alochi

Routing in Go Part 3: The last upgrade

Part 3: The last upgrade

Pagination, update endpoint, request scoped logging, and lightweight OpenAPI

Step 1: Add pagination to the store and service

Update internal/links/store.go

Update internal/links/service.go

Step 2: Add request scoped logging that actually helps

Update internal/httpapi/helpers.go

Update internal/httpapi/middleware.go

Step 3: Update handlers for pagination and PUT

Update internal/httpapi/handlers.go

Step 4: Update tests for the new behavior

Step 5: Add an OpenAPI spec without turning into a bureaucracy

Quick manual smoke test for Part 3

The real takeaway

Routing in Go Part 2: Upgrading the server so it behaves like a grown up

Part 2: Upgrading the server

Tests, auth middleware, a service layer, and request timeouts

Step 1: Restructure into a sane layout

Step 2: Move the domain and store into internal/links

Step 3: Add a service layer that owns the rules

Step 4: HTTP helpers and middleware

Step 5: Handlers that use the service layer

Step 6: Wire it all together in cmd/api/main.go

Step 7: Write tests that prove your routes behave

Step 8: Test auth middleware without hating your life

What we fixed, in human terms

Routing in Go Part 1: A small server you can grow without rewriting at midnight

A small server you can grow without rewriting at midnight

The case we are building

Step 0: Create the project

Step 1: Start with a server that is not allergic to production

Step 2: The pain we are fixing

Step 3: Build the payment link store

Step 4: Add routes that do not turn into a crime scene

Full working code

Step 5: Test the story, not just the code

Why this structure stays sane

The Role of Clear Documentation in Team Velocity

The Speed Trap

Why Velocity Actually Stalls

The Tribal Knowledge Tax

The Regression Loop

The Decision Re-Run

What to Document (And What to Ignore)

1. Context Over Syntax

2. Record Decisions (ADRs)

3. The README Is a Map

The Discipline of the Grown Engineer

The Uncomfortable Conclusion

Designing for Change, Not Control

How to write technical posts that survive AI noise

The first rule is simple

Write for people who have to make decisions

Stop writing encyclopedias

Originality is not being weird

Be specific where it matters and abstract where it helps

Explain trade offs like an adult

Add the things AI usually leaves out

Use examples that reveal judgment, not just syntax

Make your writing falsifiable

Write like a human who has met other humans

Structure matters more now than before

The strongest moat is lived specificity

Do not fight AI by pretending it does not exist

A practical checklist before you publish

Final thought

The Weekend Gold Rush and the Graveyard It Leaves Behind

Chaos engineering essentials for small teams

You do not need Netflix scale to deserve failure

What chaos engineering actually is

Why small teams need it more than big ones

Essential principle one: start with failure modes, not tools

Essential principle two: write a steady state definition

Essential principle three: start small and reversible

Essential principle four: observability is not optional

Essential principle five: automate the lessons

Essential principle six: design for graceful degradation

Essential principle seven: avoid chaos theater

Update `internal/links/store.go`

Update `internal/links/service.go`

Update `internal/httpapi/helpers.go`

Update `internal/httpapi/middleware.go`

Update `internal/httpapi/handlers.go`

Step 2: Move the domain and store into `internal/links`

Step 6: Wire it all together in `cmd/api/main.go`