Skip to content
Tutorials Center
My learning

Topics

Lesson 109 of 147 ยท Web and Networking

Building a JSON REST API

Build a JSON REST API in Go with net/http - resources and routes, JSON helpers, validation, status codes, pagination, a mutex-protected store and handler, service and store layers.

A REST API is a set of URLs that represent things (books, users, orders) and a small vocabulary of HTTP methods that act on them: GET reads, POST creates, PUT replaces, DELETE removes. Responses are usually JSON, and the HTTP status code tells the client what happened. Go is a very good fit for this job: the standard library already contains a router with method and wildcard patterns, a fast JSON encoder, and everything needed to test handlers without opening a single port.

This lesson builds a small but realistic API for a bookshelf, step by step: helper functions for JSON in and out, an in-memory store that is safe for concurrent use, the five CRUD handlers, validation, error mapping and pagination. It builds on Building an HTTP Server, Handlers, Routing and Middleware and Working with JSON.

The examples run entirely inside one program. Instead of listening on a port, they call mux.ServeHTTP with requests made by httptest.NewRequest and capture the answers with httptest.NewRecorder. That is exactly how you would unit-test a real API, and it is also how the sandbox on this site keeps programs small enough to compile. The first line of each program, //go:debug httpmuxgo121=0, switches on the Go 1.22 routing patterns (GET /books/{id}). You only need it because our runner compiles a single file without a go.mod; in a normal module whose go.mod says go 1.22 or newer, patterns just work.

Resources, routes and status codes

Start by designing the URLs. Name resources with plural nouns, put the identifier in the path, and let the HTTP method express the action:

Method and path Meaning Success status
GET /books List books (with pagination) 200 OK
POST /books Create a book 201 Created
GET /books/{id} Read one book 200 OK
PUT /books/{id} Replace a book 200 OK
DELETE /books/{id} Delete a book 204 No Content

Status codes carry the outcome: 400 Bad Request for input the server cannot parse, 404 Not Found for a missing resource, 405 Method Not Allowed for a wrong method (Go's router sends this for you), 409 Conflict for a clash with existing data, and 422 Unprocessable Entity for syntactically valid JSON that fails validation. 500 Internal Server Error is reserved for bugs and failures that are the server's fault, and its body should never leak internal details.

JSON helpers

Every handler repeats the same two chores: read a JSON body into a struct and write a JSON response. Put them into helpers once. The reader needs care, because request bodies come from strangers:

  • Limit the size with http.MaxBytesReader, or someone can send you gigabytes.
  • Call DisallowUnknownFields so that a typo such as "titel" is an error instead of being silently ignored.
  • Reject trailing data after the first JSON value.
Go Reading and writing JSON safely

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Each broken body gets a 400 with a message that helps the client developer fix the request. (An empty body is reported as plain EOF; you may want to replace that with a friendlier "body must not be empty".) Error text from encoding/json is fine for a 400 because it only describes the client's own input. For 500 errors do the opposite: log the details on the server and send a generic message.

One detail in writeJSON is easy to miss: w.WriteHeader must come after you set headers and before the first write, and once the status line is sent you can no longer change it. That is why a failed encode can only be logged.

An in-memory store

Handlers should not know how data is stored. Give them a store type with methods like Create, Get and Delete, and hide the storage behind it. Our first implementation keeps books in a map. Since the HTTP server runs every request in its own goroutine, the map must be protected: a sync.RWMutex allows many simultaneous readers or one writer (see The sync Package).

Go A store that is safe for concurrent use

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

A hundred goroutines create books at the same time and each gets a unique ID, because Create holds the write lock while it reads and increments nextID. Without the mutex this program would be a data race. Three habits from this store are worth copying:

  • ErrNotFound is a sentinel error. The handler layer checks it with errors.Is and turns it into a 404; the store never mentions HTTP.
  • List returns a copy, and Book is a value type with no pointers or slices, so callers cannot modify stored data by accident. If your struct contains slices or maps, copy those too.
  • Methods lock and defer the unlock on the next line, which keeps every return path safe.

A real application would replace this with a database, as shown in Databases with database/sql. Because handlers will depend on the behavior (a small interface) and not on the map, that swap changes only the code that constructs the store.

The handlers

Now connect the store to HTTP. A struct holds the dependencies, its methods are the handlers, and one method registers the routes. This keeps global variables out of your program and makes every handler testable.

Validation deserves its own function. It returns a map from field name to message so that the client can show each problem next to the right input:

Go A complete CRUD API, called through the router

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Read the output from top to bottom; it tells the whole story. Creating returns 201 with a Location header pointing at the new resource. The invalid body gets 422 and a fields map. A missing ID is 404, a malformed one 400. Deleting twice gives 204 and then 404. The last line is the best surprise: we never wrote any code for PATCH /books, yet the router answers 405 Method Not Allowed and fills in the Allow header with the methods that are registered for that path. That is Go 1.22 pattern routing doing its job.

Some design choices in this code are worth pointing out:

  • readBook and pathID return (value, ok) and write the error response themselves. The calling handler just returns when ok is false. This avoids repeating error handling in five places.
  • errors.Is(err, ErrNotFound) keeps the store free of HTTP knowledge. When your service layer has several error kinds, collect the mapping in one function such as statusFor(err error) int and use it everywhere.
  • PUT replaces the whole resource, so validation is the same as for create. A partial update (PATCH) needs pointer fields (*string) or a map to distinguish "not sent" from "empty".
  • The response body for an error is always the same shape, so clients can parse it without guessing.

Never put err.Error() of an unknown failure into a 500 response. A database error can reveal table names, file paths or even credentials in a connection string. Log the real error with context (and a request ID, see Handlers, Routing and Middleware) and answer with a generic {"error": "internal error"}.

Pagination

A list endpoint that returns every row works on your laptop and falls over in production. Always paginate. The simplest scheme is page and size (?page=2&per_page=10); it is easy to explain and fine for small and medium data. For large or fast-changing tables, cursor pagination (?after=<id>) is more stable because rows inserted while the user pages do not shift the pages. The mechanics are the same: validate the parameters, clamp them to sane limits and tell the client how many items exist.

Go Paginating a list with a generic helper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Look at the cases. A page beyond the end (page=9) returns an empty list rather than an error, which is the usual convention. The page size is clamped to 20 whatever the client asks for, and non-numeric or zero values are rejected with 400. The totals travel in headers (X-Total-Count), which keeps the body a plain JSON array; many APIs instead wrap the data in an object such as {"items": [...], "total": 25}. Either is fine as long as you pick one and stick to it.

One Go-specific trap: make([]T, 0, n) or a slice expression gives a non-nil empty slice, which encodes as []. A nil slice encodes as null, which breaks clients that expect an array. That is why List in the store starts from make([]Book, 0, len(...)).

Structuring a larger API

The single-file example above becomes unwieldy at around a thousand lines. The usual next step is three layers, each depending only on the one below:

TEXT
handler   parses HTTP, validates input shape, writes responses, maps errors to statuses
service   business rules ("a user can borrow at most 5 books"), no HTTP, no SQL
store     persistence (SQL, Redis, memory), returns domain types and sentinel errors

Each layer talks to the next through an interface defined by the consumer. The handler package declares type BookService interface { ... }, and the service package declares the BookStore interface it needs. The in-memory store, a database-backed store and a test fake can then be swapped freely. That pattern comes from Interface Design; the lesson on SQL in Go shows what the store layer looks like with a real database.

Things every production API adds next, all of which fit the middleware pattern from Handlers, Routing and Middleware:

  • Authentication and authorization (tokens in the Authorization header, checked in middleware).
  • Request IDs and structured logging with log/slog (Logging).
  • Timeouts via http.Server{ReadHeaderTimeout: ...} and http.TimeoutHandler, and context propagation to the database.
  • Versioning (/v1/books) so you can change the format without breaking old clients.
  • Rate limiting, CORS and compression, either in middleware or at a reverse proxy.
  • Graceful shutdown, so in-flight requests finish when the server restarts.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A client sends valid JSON for a book, but the year is 1200 and the title is empty. Which status code fits best?

    The body was well-formed JSON, so it is not a parsing problem. The semantic validation failed, which 422 describes. 500 is for server faults, never for bad client input.
  2. 2. Why does the in-memory store need a sync.RWMutex?

    net/http runs handlers concurrently. Unsynchronized map access from several goroutines is a data race and can even crash the program, so access must be locked.
  3. 3. You register only GET /books and POST /books. What does the router answer for DELETE /books?

    Since Go 1.22 the ServeMux knows which methods exist for a path. A request with another method gets 405 and an Allow header, with no extra code from you.
  4. 4. What does a JSON response contain when a handler encodes a nil []Book?

    A nil slice encodes as null, while an empty non-nil slice encodes as []. Create the slice with make(..., 0, n) when clients expect an array.
  5. 5. Which line in a handler is a mistake?

    Headers must be set before the first write. After Encode has written the body, the header is already on the wire and later Set calls have no effect.

Summary

  • Model your API as resources with plural nouns (/books, /books/{id}) and let the method express the action. Use 200, 201, 204, 400, 404, 405, 409, 422 and 500 consistently.
  • Wrap JSON in two helpers: writeJSON (headers first, then status, then body) and a readJSON that limits the size, rejects unknown fields and trailing data.
  • Hide persistence behind a store type. Protect shared state with sync.RWMutex, return copies and signal problems with sentinel errors such as ErrNotFound, which handlers map with errors.Is.
  • Go 1.22 patterns such as GET /books/{id} with r.PathValue("id") give you method routing and automatic 405 responses. Without a go.mod, the runner here needs //go:debug httpmuxgo121=0.
  • Validate input and return field-level messages with 422. Never leak internal error text in a 500.
  • Always paginate lists, clamp page sizes and remember that a nil slice encodes as null.
  • Test an API without a network by calling mux.ServeHTTP with httptest.NewRequest and httptest.NewRecorder.

Next: Streaming, SSE and WebSockets