Golang HTTP Server: net/http Routing, JSON and Status Codes

A server in a few lines

A handler is a function that receives the request and writes the response. ServeMux routes requests to handlers.

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /hello/{name}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Hello, %s!\n", r.PathValue("name"))
	})

	// httptest starts a real server on a random local port.
	srv := httptest.NewServer(mux)
	defer srv.Close()

	resp, err := http.Get(srv.URL + "/hello/gopher")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Print(resp.Status, " ", string(body))
}

The editor cannot accept connections from your browser, so the examples on this page start the server with httptest.NewServer and call it from the same program. In a real program the last part is replaced by one line that blocks and serves forever:

log.Fatal(http.ListenAndServe(":8080", mux))

Then curl localhost:8080/hello/gopher prints Hello, gopher!. ListenAndServe only returns on an error (the port is taken, for example), which is why it is wrapped in log.Fatal.

Each request runs in its own goroutine. Anything your handlers share, such as a map or a counter, needs a mutex.

Handlers

Anything with a ServeHTTP(http.ResponseWriter, *http.Request) method is an http.Handler. http.HandlerFunc adapts a plain function to that interface, and mux.HandleFunc does the conversion for you. A struct handler is handy when handlers need dependencies:

type API struct {
	db *sql.DB
}

func (a *API) listItems(w http.ResponseWriter, r *http.Request) { /* uses a.db */ }

mux.HandleFunc("GET /items", api.listItems)

The *http.Request gives you:

Routing patterns (Go 1.22)

Since Go 1.22, ServeMux patterns have the form [METHOD ][HOST]/[PATH], and paths can contain wildcards.

When two patterns match, the more specific one wins, so /items/new beats /items/{id}. If neither is more specific, for example /items/{id} and /{kind}/new (both match /items/new), registering the second one panics with a message naming both patterns. If a path matches but the method does not, the mux answers 405 Method Not Allowed with an Allow header, without any code from you.

The "/" pattern is the catch-all. That surprises people who register a home page with "/" and find it answering every unknown URL with 200. Use "GET /{$}" for the home page.

These patterns need go 1.22 or later in go.mod. With an older version line, the mux falls back to the old behavior: it reads "GET /items" as a host name followed by a path, so the route never matches and every request to /items gets a 404.

A small JSON API

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"strconv"
	"strings"
	"sync"
)

type Item struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

type Store struct {
	mu     sync.Mutex
	items  map[int]Item
	nextID int
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json") // headers first
	w.WriteHeader(status)                              // then the status
	json.NewEncoder(w).Encode(v)                       // then the body
}

func (s *Store) getItem(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.Atoi(r.PathValue("id"))
	if err != nil {
		http.Error(w, "id must be a number", http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	item, ok := s.items[id]
	s.mu.Unlock()
	if !ok {
		http.Error(w, "item not found", http.StatusNotFound)
		return
	}
	writeJSON(w, http.StatusOK, item)
}

func (s *Store) createItem(w http.ResponseWriter, r *http.Request) {
	var in Item
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // refuse bodies over 1 MB
	if err := json.NewDecoder(r.Body).Decode(&in); err != nil || in.Name == "" {
		http.Error(w, "invalid JSON body", http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	s.nextID++
	in.ID = s.nextID
	s.items[in.ID] = in
	s.mu.Unlock()

	w.Header().Set("Location", fmt.Sprintf("/items/%d", in.ID))
	writeJSON(w, http.StatusCreated, in)
}

func main() {
	store := &Store{items: map[int]Item{}}
	mux := http.NewServeMux()
	mux.HandleFunc("GET /items/{id}", store.getItem)
	mux.HandleFunc("POST /items", store.createItem)

	srv := httptest.NewServer(mux)
	defer srv.Close()

	show := func(resp *http.Response, err error) {
		if err != nil {
			fmt.Println("error:", err)
			return
		}
		defer resp.Body.Close()
		body, _ := io.ReadAll(resp.Body)
		fmt.Printf("%d %s", resp.StatusCode, body)
		if loc := resp.Header.Get("Location"); loc != "" {
			fmt.Println("  Location:", loc)
		}
	}

	show(http.Post(srv.URL+"/items", "application/json", strings.NewReader(`{"name":"lamp"}`)))
	show(http.Get(srv.URL + "/items/1"))
	show(http.Get(srv.URL + "/items/99"))
	show(http.Get(srv.URL + "/items/abc"))
	show(http.Post(srv.URL+"/items", "application/json", strings.NewReader(`{bad json`)))

	req, _ := http.NewRequest(http.MethodDelete, srv.URL+"/items/1", nil)
	resp, err := http.DefaultClient.Do(req)
	if err == nil {
		fmt.Println(resp.StatusCode, "Allow:", resp.Header.Get("Allow"))
		resp.Body.Close()
	}
}

The last request uses DELETE, which no route accepts, and the mux answers 405 with Allow: GET, HEAD on its own: those are the methods registered for that path (a GET route also accepts HEAD).

Status codes and the order of writes

A response has three parts, and they must be written in order: headers, status, body.

1. w.Header().Set(...) changes headers. It has an effect only until the status is sent.
2. w.WriteHeader(code) sends the status line and the headers.
3. w.Write(...) (or fmt.Fprint(w, ...), or an encoder) sends the body. If WriteHeader has not been called, the first Write sends 200 OK first.

Consequences:

• Setting a header after the body has started does nothing.
• Calling WriteHeader twice logs http: superfluous response.WriteHeader call and keeps the first status.
• After an error response, return. http.Error does not stop your handler, and code after it keeps writing into the same response.

Use the named constants (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) rather than bare numbers. http.StatusText(404) returns "Not Found".

Middleware

Middleware is a function that takes a handler and returns a handler, doing something before or after calling the next one:

package main

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

func requireKey(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.Header.Get("X-API-Key") != "secret" {
			http.Error(w, "unauthorized", http.StatusUnauthorized)
			return
		}
		next.ServeHTTP(w, r)
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
}

func (s *statusRecorder) WriteHeader(code int) {
	s.status = code
	s.ResponseWriter.WriteHeader(code)
}

func logRequests(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(rec, r)
		fmt.Printf("log: %s %s -> %d\n", r.Method, r.URL.Path, rec.status)
	})
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /report", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "the report")
	})

	handler := logRequests(requireKey(mux)) // outermost runs first
	srv := httptest.NewServer(handler)
	defer srv.Close()

	for _, key := range []string{"", "secret"} {
		req, _ := http.NewRequest(http.MethodGet, srv.URL+"/report", nil)
		req.Header.Set("X-API-Key", key)
		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			fmt.Println(err)
			return
		}
		resp.Body.Close()
		fmt.Println("client got:", resp.Status)
	}
}

The log: line always appears before client got: for the same request. The handler goroutine prints it before it returns, and the server does not finish the response until the handler returns.

The statusRecorder embeds the real ResponseWriter and overrides only WriteHeader, which is the standard way to observe the status code from middleware.

Production settings

http.ListenAndServe uses a server with no timeouts, so a slow client can hold a connection open indefinitely. Configure an http.Server explicitly for anything exposed to the internet, and shut it down gracefully:

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

go func() {
	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		log.Fatal(err)
	}
}()

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done() // wait for Ctrl+C or a SIGTERM from the orchestrator

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil { // finish in-flight requests
	log.Println("shutdown:", err)
}

Shutdown stops accepting new connections and waits for active requests to finish, up to the context's deadline. ListenAndServe returns http.ErrServerClosed as soon as Shutdown starts, which is why that error is not treated as a failure. For long-running handlers, pass r.Context() down so they stop when the client goes away.

Serving static files is one line: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Common mistakes

• Not returning after http.Error. The handler keeps running and writes more into the response.
• Setting headers after writing the body. They are silently dropped.
• Registering the home page on "/". It becomes the catch-all for every unknown path. Use "/{$}".
• Sharing state between handlers without a lock. Requests run concurrently.
• Using the default server in production. It has no timeouts; set them on an http.Server.
• Routing patterns ignored. If "GET /x/{id}" never matches, check that go.mod says go 1.22 or later.