Week 10: Building a REST API with net/http

1. Handlers & ServeMux

An HTTP handler is anything satisfying http.Handler — in practice, almost always written as a plain function matching func(w http.ResponseWriter, r *http.Request), wrapped by http.HandlerFunc.

func healthHandler(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("ok"))
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /health", healthHandler)
    mux.HandleFunc("GET /users/{id}", getUserHandler)

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

Since Go 1.22, ServeMux supports method matching ("GET /health") and path parameters ({'{'}id{'}'}, read with r.PathValue("id")) directly — a real router (Week 11's chi) is worth reaching for once route groups and richer patterns matter, but the standard library alone now covers a surprising amount of ground.

2. Encoding & Decoding JSON

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

type UserResponse struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

func createUserHandler(w http.ResponseWriter, r *http.Request) {
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "invalid JSON body", http.StatusBadRequest)
        return
    }

    user := UserResponse{ID: 1, Name: req.Name, Email: req.Email} // pretend this was saved

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(user)
}

The backtick-delimited json:"name" annotations are struct tags — metadata read by encoding/json via reflection, mapping a Go field name to the JSON key it should read from and write to (independent of Go's own exported-identifier naming rules from Week 8).

3. Status Codes & Headers

Headers must be set before WriteHeader is called — once the status line is written, headers are locked in. This ordering trips up nearly everyone the first time.

w.Header().Set("Content-Type", "application/json") // 1. headers first
w.WriteHeader(http.StatusCreated)                    // 2. then the status
json.NewEncoder(w).Encode(user)                       // 3. then the body

A quick reference for the status codes a REST API reaches for constantly: 200 OK (success), 201 Created (a POST that made something new), 204 No Content (success, nothing to return), 400 Bad Request (the client sent something invalid), 404 Not Found, and 500 Internal Server Error (something broke on your end). If a handler never calls WriteHeader explicitly, Go defaults to 200 the moment the first byte is written to the body.

4. Graceful Shutdown

http.ListenAndServe alone offers no way to stop cleanly — a Ctrl+C or a container orchestrator's stop signal kills every in-flight request instantly. A real service listens for that signal and gives active requests a chance to finish first.

func main() {
    srv := &http.Server{Addr: ":8080", Handler: mux}

    go func() {
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatalf("server error: %v", err)
        }
    }()

    stop := make(chan os.Signal, 1)
    signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
    <-stop // blocks until Ctrl+C or a container stop signal

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

    log.Println("shutting down...")
    if err := srv.Shutdown(ctx); err != nil {
        log.Fatalf("forced shutdown: %v", err)
    }
    log.Println("server stopped cleanly")
}

srv.Shutdown(ctx) stops accepting new connections immediately, but lets in-flight requests finish — up to the context's timeout, after which it gives up and returns an error. This is exactly the context-driven cancellation pattern from Week 7, applied to the server's own lifecycle.

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.