Writing JSON Responses

A response has three parts and they leave the server in a fixed order: headers, then a status code, then the body. Go lets you write them in any order in your code, and quietly drops the ones that arrive too late. Getting that order right is most of this lesson.

The order

w.Header() returns a map of header names to values. Set Content-Type to application/json there, so the client knows how to read what follows. Then call w.WriteHeader with the status code. Then write the body. WriteHeader is the point of no return. Once a 2xx to 5xx status has been sent the server has taken its own copy of the header map, and anything you set afterwards goes nowhere.

Marshal before you commit

json.Marshal turns a Go value into bytes and returns an error alongside them. json.NewEncoder(w).Encode(v) is the shorthand for the same work: it converts and writes in one call, and it appends a newline. The difference shows up on failure. Encode writes straight to the client, so if conversion fails partway the status is already 200 and the body is cut off. Converting into a byte slice first leaves you free to send a 500 instead.

What trips people up

If you never call WriteHeader, the first Write sends 200 on your behalf. So a WriteHeader(http.StatusCreated) placed after an Fprintf does nothing at all, and the server logs a complaint about a superfluous call.

package main

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

type book struct {
	Title string `json:"title"`
	Pages int    `json:"pages"`
}

// writeJSON converts first, then sets headers, then the status, then the body.
func writeJSON(w http.ResponseWriter, status int, v any) {
	buf, err := json.Marshal(v)
	if err != nil {
		// Nothing has been sent yet, so a 500 is still possible here.
		http.Error(w, "could not encode response", http.StatusInternalServerError)
		return
	}
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_, _ = w.Write(buf) // a write error means the client left; nothing to do
}

func main() {
	rec := httptest.NewRecorder()
	writeJSON(rec, http.StatusOK, book{Title: "Dune", Pages: 412})
	fmt.Println(rec.Code)
	fmt.Println(rec.Header().Get("Content-Type"))
	fmt.Print(rec.Body.String())
}

// Output:
// 200
// application/json
// {"title":"Dune","pages":412}

// Shorthand: converts and writes in one call, and adds a trailing "\n".
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
enc := json.NewEncoder(w)
enc.SetEscapeHTML(false) // keep <, > and & as themselves, not < etc.
enc.SetIndent("", "  ") // pretty-print; costs bytes, useful for a debug endpoint
if err := enc.Encode(b); err != nil {
	// Too late for a status. Log it and move on.
	log.Printf("encode response: %v", err)
}

// Wrong: the body goes first, which sends 200 and clears the header map.
func badHandler(w http.ResponseWriter, r *http.Request) {
	fmt.Fprint(w, `{"ok":true}`)
	w.Header().Set("Content-Type", "application/json") // ignored
	w.WriteHeader(http.StatusCreated)                  // ignored, and logged
}

// Right: headers, then status, then body.
func goodHandler(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	fmt.Fprint(w, `{"ok":true}`)
}

func deleteBook(w http.ResponseWriter, r *http.Request) {
	if err := store.Delete(r.PathValue("id")); err != nil {
		http.Error(w, "could not delete", http.StatusInternalServerError)
		return
	}
	// 204 means "it worked, there is nothing to send". No Content-Type,
	// no body: a body on a 204 is a protocol error.
	w.WriteHeader(http.StatusNoContent)
}