Stage 3 · Build

HTTP & REST APIs

JSON APIs

Decode request bodies, validate payloads, encode responses, and handle encoding/json error paths.

8 min readBuilding Backend ApplicationsBuild

Decoding Requests

Use json.NewDecoder to decode request bodies. It streams from the body directly, avoiding the need to read the entire body into memory first. Always close the body after decoding.

Godecoding-a-json-request-body.go

14 linesLn 1, Col 1Go

json.NewDecoder reads directly from r.Body. It handles streaming, so large bodies do not blow up memory. If you need the raw bytes first, use io.ReadAll.

Validation

Always validate request payloads. Check required fields, ranges, string formats, and business rules. Return specific error messages so clients know what to fix.

Gomanual-validation.go

29 linesLn 1, Col 1Go

Use 422 Unprocessable Entity for validation errors. It tells the client the request was well-formed but semantically invalid.

Use go-playground/validator for complex rules

For applications with many endpoints, the go-playground/validator package provides struct tag validation. Add validate:"required,min=1,max=100" to struct fields and call validator.New().Struct(req).

Encoding Responses

Use json.NewEncoder to write JSON responses. It handles escaping, streaming, and error handling. Set Content-Type before writing.

Goencoding-json-responses.go

17 linesLn 1, Col 1Go

Always set Content-Type before writing. The json.Encoder automatically handles struct-to-JSON conversion and special character escaping.

Error Paths

Your API needs consistent error handling for decode failures, validation errors, not-found errors, and internal errors. Each should return the correct status code and a structured error body.

Gostructured-error-response.go

20 linesLn 1, Col 1Go

Include a machine-readable code and human-readable message. Clients use the code to branch on error type; logs use it for alerting.

Struct Tags

Struct tags control how fields serialize to JSON. The json tag defines the field name in JSON. Use omitempty to skip zero-value fields. Use the dash to exclude fields entirely.

Gocommon-json-struct-tags.go

9 linesLn 1, Col 1Go

The dash tag prevents Password from appearing in any JSON output. omitempty omits Email if it is an empty string. This gives you precise control over your API surface.

Streaming JSON

For large responses like paginated lists, stream JSON with json.Encoder instead of building the entire response in memory. This keeps memory usage constant regardless of list size.

Gostreaming-a-list-response.go

18 linesLn 1, Col 1Go

Streaming avoids buffering the entire list. For very large results, combine streaming with cursor-based pagination.

Handle decode errors explicitly

Never ignore json.Decode errors. Malformed JSON is the most common API error. Return 400 with a clear message like 'invalid JSON in request body' so clients can fix their requests.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.