Handlers, Requests & Responses

Most handlers are plain functions. A plain function does not automatically satisfy the interface, so Go provides http.HandlerFunc. This is an adapter type that wraps a function and gives it a ServeHTTP method. When you call http.HandleFunc, this conversion happens automatically:

Use http.HandleFunc for plain functions, which is the most common case. Use http.Handle when you need a custom type with fields or methods, like pingHandler. Both register an http.Handler on the multiplexer (mux). Middleware and library code usually pass http.Handler values around directly, so knowing the interface behind the shortcut is helpful.

Reading the request

The *http.Request carries everything the client sent. The fields you will reach for most often are r.Method, r.URL.Path, r.Header, r.URL.Query(), and r.Body.

Query parameters

The greetHandler reads a query parameter from the URL:

The r.URL.Query() method parses the query string into a url.Values map. Calling .Get("name") returns an empty string if the key is absent. When the parameter is missing, http.Error sends a 400 Bad Request response, and the handler returns immediately.

The request body

For POST requests, the body arrives through r.Body, which is an io.Reader. The echoHandler reads the entire body and sends it right back:

The defer r.Body.Close() statement runs when the function returns. Go's HTTP server actually closes the request body for you after a handler returns, so this is more a good habit than a strict requirement here. It becomes mandatory later, when you read response bodies as an HTTP client. The io.ReadAll function reads all bytes from the reader and returns a []byte slice.

Notice that w.Write(body) writes the bytes exactly as they are, with no trailing newline. The body you send is exactly the body you get back.

Writing the response

The http.ResponseWriter has three main operations: setting headers, setting the status code, and writing the body. You generally need to perform them in a specific order.

Headers first. Call w.Header().Set(key, value) before anything else. Headers are part of the HTTP response preamble and usually go out before the body.

Status code second. Call w.WriteHeader(statusCode) to send the status. If you skip this step, Go automatically sends a 200 OK the first time you call w.Write.

Body last. Call w.Write([]byte) or fmt.Fprintf(w, ...) to write the actual response body.

The ordering in echoHandler is the standard pattern to follow:

For error responses, http.Error handles all three steps in a single call:

It sets the status, writes the message as the body, and automatically adds Content-Type: text/plain; charset=utf-8 and X-Content-Type-Options: nosniff.

Here are the status codes this course uses:

Try to use http.StatusXxx constants rather than bare integers. They are self-documenting and much easier to search for in your codebase.

Beginner traps

Calling WriteHeader twice. Only the first call takes effect. Go logs a "superfluous response.WriteHeader call" warning to stderr, but the handler keeps running. This usually happens when a handler calls http.Error but forgets to return afterward. The error response goes out, and a second write attempt is silently dropped.

Writing the body before the status. The first call to w.Write or fmt.Fprintf(w, ...) flushes the response with a 200 OK if WriteHeader was never called. Any WriteHeader call after that is ignored. Set the status before writing the body.

Skipping Content-Type for JSON. Go sniffs the first 512 bytes and guesses a content type when you leave it out. For plain text in a demo, that is fine. However, the next chapter returns JSON responses. You will need to set Content-Type: application/json explicitly for those, because the sniffer might not guess correctly.

What's Next

Chapter 16 introduces http.NewServeMux and Go 1.22's method-plus-path patterns like "POST /tasks" and "GET /tasks/{id}", replacing the simple path strings we have used so far. That multiplexer is what the Task API will use for all its routing.