REST & OpenAPI
Routes, pagination envelope, filtering, and error shape.
Routes
Every enabled resource exposes:
GET /api/{name} list
GET /api/{name}/{id} get
POST /api/{name} create
PATCH /api/{name}/{id} update (partial)
DELETE /api/{name}/{id} delete{id} addresses LookupField || PK.Column || "id".
List query
| Param | Meaning |
|---|---|
page / limit | pagination (defaults 1 / 50, cap 500; response echoes effective values) |
search | ILIKE-OR across the resource's searchable fields |
sort | "col" or "-col"; must be in the sortable allowlist or 400 |
{field} | per-field equality for filterable fields (generated ListInput) |
{
"data": [{ "id": "...", "title": "Acme" }],
"total": 132,
"page": 1,
"limit": 50
}Writes
POSTtakes theCreateBodyJSON; server fills PK (unless prompt), defaults,from:fields, and timestamps.PATCHtakes a partialUpdateBody; absent ≠ zero thanks to pointer fields. Empty effective patch →400.- Unknown keys are dropped silently (mass-assignment guard); readonly keys are dropped, not errored.
Errors
RFC 9457 problem details with the Brick code mapping:
| Status | Helper | When |
|---|---|---|
400 | BadRequest | bad sort, empty update, malformed input |
401 | Unauthorized | missing session / required from: source |
403 | Forbidden | guard Check denial |
404 | NotFound | missing or out-of-scope row |
409 | Conflict | unique violation (SQLSTATE 23505) |
422 | Unprocessable | field validation failures (detail list) |
500 | — | hidden internals + request_id; send the ID when reporting |
OpenAPI
Huma serves the spec at GET /openapi.json (application/openapi+json;
same bytes as b.OpenAPISpec()) and Stoplight docs at /docs. Mount the
Scalar viewer for interactive docs with an absolute spec URL built per
request (scalar-go rejects relative URLs; see App setup):
html, err := brick.ScalarDocsHTML(scheme + "://" + req.Host + "/openapi.json")
b.Router().GET("/reference", func(w http.ResponseWriter, req bunrouter.Request) error {
w.Header().Set("Content-Type", "text/html; charset=utf-8")
_, _ = w.Write([]byte(html))
return nil
})