Handlers and requests
Write handlers that receive typed input, return typed output, and turn errors into proper HTTP responses.
Before you start
Read Routing to see how handlers are registered.
Steps
1. Describe the input
An input struct says where each value comes from:
// Note is what the API returns.
type Note struct {
ID int `json:"id"`
Title string `json:"title"`
Body string `json:"body"`
Tags []string `json:"tags,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
// CreateNote is the input for POST /notes. It binds from JSON or a form,
// and the validate rules run before the handler.
type CreateNote struct {
Title string `json:"title" validate:"required|max:200"`
Body string `json:"body" validate:"max:10000"`
Tags []string `json:"tags" validate:"max:5|distinct|alpha_dash"`
}
// Validate runs after the tag rules pass, for checks tags can't express.
func (in CreateNote) Validate(context.Context) error {
if strings.EqualFold(strings.TrimSpace(in.Title), "untitled") {
return validate.Fail("title", "Please give the note a real title.")
}
return nil
}
// ListNotes reads its input from the query string.
type ListNotes struct {
Limit int `query:"limit" validate:"min:0|max:100"`
}
// NoteID reads the {id} path parameter.
type NoteID struct {
ID int `path:"id"`
}(Copied from examples/notes, region
types.)
| Tag | Source |
|---|---|
json:"title" | JSON body. Also used as the form field name when there’s no form tag |
form:"title" | URL-encoded or multipart form field |
query:"page" | Query string ([]T collects repeated values) |
path:"id" | Path wildcard {id} |
header:"X-Token" | Request header |
validate:"required|max:200" | Not a source: validation rules checked after binding |
Values are converted to the field’s type: strings, numbers, booleans,
time.Duration, time.Time (RFC 3339), pointers, and any type with an
UnmarshalText method. Uploaded files are *multipart.FileHeader or
[]*multipart.FileHeader with a form tag. See the
binding reference.
2. Write a typed handler
// illustrative
func (h *Notes) Create(c *web.Ctx, in CreateNote) (Note, error) {
return h.create(in.Title, in.Body), nil
}
func (h *Notes) Show(c *web.Ctx, in NoteID) (Note, error) {
note, ok := h.find(in.ID)
if !ok {
return Note{}, web.Error(http.StatusNotFound, "note not found")
}
return note, nil
}Register it with web.H (H for handler):
// illustrative
api.Post("", web.H(notes.Create)).Name("create").Status(http.StatusCreated)web.H inspects the input type once, at startup. It panics then if the
type can’t be bound or a validate tag is wrong (an unknown rule, a bad
parameter), so a mistake never waits for the first request.
web.H has nothing to do with Gin’s gin.H map: it adapts a typed
handler. A map is answered as JSON here too (map[string]any), with no
special type.
3. Choose the response
| Return | Response |
|---|---|
| Any value (struct, slice, map…) | JSON with the route’s status: 200, or what Status sets on the route; no body with 204 or 205 |
web.Empty{} | 204 without a body (or the route’s status, still without a body) |
web.Created(v) | 201 with JSON |
web.JSON(status, v) | JSON with any status |
web.NoContent() or a nil web.Responder | 204 |
web.Redirect(url) / web.RedirectRoute(name, args...) | 303 See Other |
web.Text(status, s) | Plain text |
Your own type with Respond(c *web.Ctx) error | Whatever it writes |
For an API, return a typed value and put the status on the route:
.Status(http.StatusCreated) for a route that creates something,
web.Empty for one with nothing to answer (a deletion). The handler’s
signature and the route then say what the request answers, which the
API’s description reads (Describe an API with OpenAPI);
Status takes 2xx statuses only, and errors are written as usual.
Status sets what a web.H handler’s result answers: a
web.Responder, a plain handler and a web.WrapHandler route write their
own status, and ignore it. Use web.Responder as the output type when
one handler returns different kinds of responses, chosen as it runs:
pages’ redirects, say.
Handlers can also be plain func(c *web.Ctx) error and write with
c.JSON, c.Text, c.HTML, c.Blob, c.Redirect, c.RedirectRoute or
c.NoContent.
4. Return errors
Return an error and let the framework respond:
web.Error(status, "message")gives that status with your message, which is shown to the client.- Your own errors can implement
HTTPStatus() int(web.StatusCoder) to pick a status, for example a repository’s “not found” error returning 404. The method isHTTPStatus, not go-kit’sStatusCode. - Anything else is a 500, and its message is not shown to clients
unless
APP_DEBUG=true.
Error responses are chosen per client:
API clients (sending
Accept: application/json, a JSON body, orX-Requested-With: XMLHttpRequest), and every request underweb.JSONErrors(below), get RFC 9457 problem details:{ "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "detail": "The given data was invalid.", "errors": { "title": "The title field is required." }, "request_id": "dikxmvlw5ml243cr" }Binding and validation errors fill the
errorsobject, keyed by field name. Your own errors can do the same by implementingFieldErrors() map[string]string(web.FieldErrorer).Browsers get an HTML error page. With
APP_DEBUG=trueit shows the error chain, the stack trace for panics, and request details (withAuthorizationandCookieheaders redacted).A project made with
anetos newshows its error pages in its own layout:routes/web.gopassesviews.ErrorPage(inviews/errors.templ, yours to change) to the router’sErrorPages. It gets aweb.ErrorPage: the status, its translated title, the error’s message for the visitor if any (never a 5xx’s internals), the field errors of a 4xx that isn’t a form’s redirect, and the request ID. WithAPP_DEBUG=true, a 5xx still shows the framework’s page with its details. A URL that matches no route runs only the global middleware, so its page has no session: the header shows a guest’s links. If the page fails to render (or panics), the framework’s is sent and the failure logged. Another app adds it the same way:// illustrative r.ErrorPages(func(_ *web.Ctx, e web.ErrorPage) view.Component { return views.ErrorPage(e) })
An API can’t count on its clients asking for JSON: curl, fetch
without headers and many HTTP libraries send Accept: */* or nothing,
and would get the HTML page. Put web.JSONErrors on the
API’s routes, and their errors are problem details whatever the client
sends, never a page or a redirect back to a form:
// The API's errors are JSON problem details, whatever the client
// accepts, and a guest gets a 401, not the login page.
var api handlers.API
v1 := r.Group("/api", web.JSONErrors, a.TokenMiddleware, a.Require) // Authorization: Bearer <token>
v1.Get("/projects", web.H(api.Projects)).Name("api.projects")
v1.Get("/projects/{project}/issues", web.H(api.Issues)).Name("api.issues")
v1.Post("/projects/{project}/issues", web.H(api.CreateIssue)).Name("api.issues.create").Status(http.StatusCreated)
v1.Get("/projects/{project}/issues/{number}", web.H(api.Issue)).Name("api.issues.show")(Copied from examples/tracker/routes/tracker.go, region api.)
Under it, c.WantsJSON() (and web.WantsJSON(r) in middleware) is
true, so everything that treats API clients differently does so:
auth’s Require answers 401 rather than redirecting to the login
page. In debug mode the error’s details are in the problem’s debug
member. Put it before the middleware whose answers it should change,
such as Require: it acts from its place in the chain on. A project
made with anetos new --stack=api puts it on every request
(r.UseGlobal(web.JSONErrors) in routes/api.go), so a URL that
matches no route gets a JSON 404 too, and a panic in middleware a JSON
500. On a group, only that group’s routes are affected: a URL under the
group’s prefix that matches none of them gets the router’s usual 404.
Panics in handlers are recovered and handled like errors. Every 5xx is logged with the request ID.
Two edge cases:
- The response already started. If a handler writes part of a response and then fails or panics, the error is logged and the connection is aborted, so the client sees a failed response rather than a truncated one that looks complete.
- Cancellation. If the client went away, nothing is written (logged as
499). If a handler returns
context.Canceledfrom some internal context while the client is still waiting, it’s a 500.
How binding works
- The body is decoded: JSON (
Content-Type: application/jsonor+json) into the whole struct, or a form intoform/json-named fields. Other content types get 415, and bodies overHTTP_MAX_BODYget 413. - Then query, header and path values are applied. Fields with
these tags can never be set from the body, so a client can’t override
{id}by sending"ID": 999in JSON. - Conversion failures give 400 with each bad field listed.
- The
validatetag rules run. Failures give 422 with a message per field. See Validation. - If they pass and the input has
Validate(ctx) error, it runs.validate.Fail(field, message)(or a*validate.Errors) gives 422, anHTTPErrorkeeps its own status, and any other error is a 500.
Coming from another framework? The input struct plays the role of a Django form, a Laravel form request, or Rails’ strong parameters and model validations: it declares the input, its rules (
required|email) and extra checks, and is validated before your handler runs.
Testing it
Send requests to the app’s router with anetostest:
// illustrative
app := anetostest.New(t, setup)
app.PostJSON("/notes", map[string]string{"title": "Hi"}).
AssertCreated().
AssertJSONPath("title", "Hi")See Test your app. A router alone works
with httptest too: r.ServeHTTP(rec, req).
Common problems
| Symptom | Cause | Fix |
|---|---|---|
Panic at startup: input type … must be a struct | web.H handler takes a non-struct | Wrap inputs in a struct |
Panic at startup: unsupported field type | e.g. a map field with a query tag | Use supported types or read c.Request() yourself |
Panic at startup: validate: … unknown rule | A typo in a validate tag, or a custom rule registered after the route | Check the rules reference; register custom rules in init |
| Field stays empty for JSON | The field has a path/query/header tag, or its JSON name differs | Check tags; body can’t fill those fields |
415 Unsupported Media Type | Missing or wrong Content-Type | Send application/json or a form content type |
| 500 with no details | Production mode hides internal errors | Check the log line with the same request_id, or set APP_DEBUG=true locally |