Routing with ServeMux

In Chapter 15, http.HandleFunc wrote routes into a package-level global called http.DefaultServeMux, and passing nil to http.ListenAndServe(":8080", nil) told the server to use it.

That design creates friction as a codebase grows. First, the pattern was just a path string. A route like "/greet" matched every HTTP method. Distinguishing a GET request from a POST request meant reading r.Method inside the handler and returning a 405 error yourself. Second, http.DefaultServeMux is shared across all packages. Any imported library can write routes into it, meaning two packages can silently overwrite each other. A global mux is also harder to pass to an httptest server during testing without causing side effects. We will look closer at testing in Chapter 24.

http.NewServeMux() creates a fresh mux you control:

Notice that the second argument changes from nil to mux. Everything else stays the same. You just call mux.HandleFunc instead of http.HandleFunc. This gives you a single routing value that is explicitly wired up and easy to pass around.

Method-plus-path patterns

Before Go 1.22, the pattern "/tasks" matched any method. To route GET and POST to different handlers, every Go team either wrote a switch r.Method inside a single handler or reached for chi or gorilla/mux. Go 1.22 added method routing to the pattern string itself.

Here is the complete main.go for this chapter:

"GET /tasks" and "POST /tasks" are two separate registrations for the same path. A GET request goes to listTasks, while a POST request goes to createTask. The mux handles the dispatching automatically, so the handlers never need to inspect r.Method.

The handlers here are just stubs. listTasks returns a hard-coded JSON array, createTask acknowledges the request with a 201 status, and getTask echoes a path segment. We do not have database storage yet. That arrives in Section 4. For now, we are only focusing on routing.

Reading path wildcards

The pattern "GET /tasks/{id}" introduces a wildcard: {id} matches exactly one non-empty path segment. Inside the handler, r.PathValue("id") returns that segment as a string:

A request to GET /tasks/42 delivers "42". GET /tasks/abc delivers "abc". Two cases that do not match this pattern are /tasks/ (an empty segment) and /tasks/42/notes (two segments past /tasks/). In Chapter 21, we will convert this string to an integer using strconv.Atoi and look up the task in a database. For now, echoing the ID back to the client confirms the routing works.

Automatic 405 and 404

We registered "GET /tasks" and "POST /tasks" but nothing for DELETE /tasks. Start the server with go run . and try:

The DELETE request gets back a 405 Method Not Allowed response with an Allow: GET, HEAD, POST header. We did not have to write any code for this. The mux derives the set of allowed methods from the patterns registered for that path and sends the 405 automatically. Notice that HEAD is in the list. Registering a GET handler also serves HEAD requests for free.

GET /nope returns 404 page not found. These two error codes mean different things, and API clients care about the distinction:

• 404 Not Found: No pattern matches this path. The server has never heard of it.
• 405 Method Not Allowed: The path exists in the mux, but not for the requested method.

Pattern specificity

When two patterns could match the same request, the more specific one wins regardless of registration order. A fixed segment beats a wildcard: if you registered both "GET /tasks/done" and "GET /tasks/{id}", a request to /tasks/done goes to "GET /tasks/done".

You can also register a subtree pattern by ending a path with a slash. For example, "GET /tasks/" would match /tasks/ and everything under it. We do not register one here. For a REST API where each sub-path is its own named route, a wildcard or fixed segment is usually the right choice, rather than a subtree.

When to reach for chi or gorilla

The standard library ServeMux covers everything the Task API needs. You would consider a third-party router for:

• Clean middleware chaining (chi's r.Use(...), for example)
• Regex or typed path constraints ({id:[0-9]+} to reject non-numeric ids at the router level)
• Route groups that scope middleware to a subset of paths
• Sub-routers mounted at a path prefix

Both chi and gorilla/mux are mature options. For this course, the standard library is enough, and Go 1.22 is the reason why.

What's Next

Chapter 17 covers JSON encoding and decoding with encoding/json. The listTasks handler returns a hard-coded string today, so next we will encode real Go structs into responses and decode request bodies properly.