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

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.”

Share this writing

Twitter LinkedIn

More notes

Reducing Blast Radius, Not Achieving Perfection

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