3.11 · Guides
Generate CRUD routes¶
crud(...) generates model-backed routes. Include it once in the app for plain
CRUD, or apply it to a class when you need get_queryset/to_schema hooks
or handwritten @http.* actions beside the generated ones.
from hinoki import Hinoki, Schema, crud
from app.models import Post
from app.security import editor
class PostOut(Schema, model=Post): ...
class PostCreate(Schema):
title: str
slug: str
body: str
posts = crud(
Post,
path="/posts",
read=PostOut,
create=PostCreate,
delete=True,
access=editor,
owner="author_id",
)
app = Hinoki(include=[posts])
Add code with the class form. The class extends API (its only base);
get_queryset(self, principal) and
to_schema(self, item) are the only hooks; anything else is a handwritten
action:
from typing import Any
from hinoki import API, Caller, crud, http
from hinoki.orm import QuerySet
@crud(Post, path="/posts", read=PostOut, create=PostCreate, access=editor)
class Posts(API):
def get_queryset(self, principal: Caller[Any] | None) -> QuerySet[Post]:
return Post.filter(published=True).order_by("-id")
@http.get("/health")
async def health(self) -> dict[str, str]:
return {"status": "ok"}
app = Hinoki(include=[Posts])
A generated action is generated or handwritten, never both: defining
list, retrieve, create, update or delete in the class while crud
generates it raises RegistrationError at declaration. To write list or
retrieve yourself, pass omit=("list",) (or "retrieve"); other actions are
generated only when you give their schema or delete=True. The write hooks
store, change, remove and written_queryset are the supported way to
change what a generated write does; see
Hooks in the class form.
Access per action¶
access= takes one Access, which protects every generated action
including reads, or CrudAccess to set actions apart. An action without its
own entry uses default; None means public:
from hinoki import CrudAccess
posts = crud(
Post,
path="/posts",
read=PostOut,
create=PostCreate,
delete=True,
access=CrudAccess(default=editor, list=None, delete=admin),
)
Here list is public, retrieve and create need editor, delete needs admin.
Unknown action names raise TypeError. Writes with no policy still need
public_writes=True.
Hooks in the class form¶
Apply @crud(...) to a class that extends API to add code beside the
generated actions: the hooks get_queryset, to_schema, written_queryset,
store, change and remove, and handwritten @http.* actions. Schemas and
options are crud(...) keywords, and the class is included once in the app.
from typing import Any
from hinoki import API, Caller, Hinoki, crud, http
from hinoki.orm import QuerySet
@crud(
Post,
path="/posts",
read=PostOut,
create=PostCreate,
access=editor,
owner="author_id",
)
class Posts(API):
def get_queryset(self, principal: Caller[Any] | None) -> QuerySet[Post]:
return Post.filter(published=True).order_by("-id")
@http.get("/health")
async def health(self) -> dict[str, str]:
return {"status": "ok"}
app = Hinoki(include=[Posts])
The generated actions are ordinary API routes, visible to OpenAPI, the
hinoki routes command and the route registry. The class is mounted once; no import-time or
global auto-registration occurs. A model's read schema and write schemas must
match its fields. See Schemas for model-derived schemas.
The sections below describe the options by their crud(...) keyword (read,
create, update, delete, access, owner, identity_key, assign,
pagination, public_writes, omit).
Generated actions¶
List and retrieve are generated by default. Writes are opt-in:
| Keyword | Action | Method and path | Success |
|---|---|---|---|
| Always | list |
GET /posts |
Paginated Page[PostOut] |
| Always | retrieve |
GET /posts/{item_id} |
PostOut |
create=PostCreate |
create |
POST /posts |
201, PostOut |
update=PostPatch |
update |
PATCH /posts/{item_id} |
200, PostOut |
delete=True |
delete |
DELETE /posts/{item_id} |
204, no body |
Generated writes require access=..., unless public_writes=True is set
deliberately. Reads are public by default; CrudAccess(list=..., retrieve=...)
protects them.
Writes run in a transaction. pagination selects the page-number policy for
the generated list route.
On Kiso, eligible generated routes are selected automatically and execute in Rust. List, retrieve, create, PATCH update and delete are eligible when their schemas and model are supported and the resource has no access policy, owner/assignment rule or custom hook. Unsupported and stale plans keep using the Python request lane. See Serving for the runtime boundary and staleness behavior; no public switch is required.
Reuse and customization¶
CRUD configuration is plain Python values, so share it the same way: one
Access or CrudAccess object passed to every crud(...) call, or a small
helper that wraps crud(...) with your defaults.
Generated create actions return 409 Conflict when the database rejects a
unique constraint by default. Register an error handler for the database's
unique-violation type to choose an application-specific response.
Mixins can provide reusable decorated routes or hooks to a decorated class.
access applies to generated actions only;
handwritten decorated methods keep the policy on their own
@http.* decorator, so protect those routes explicitly.
Use get_queryset(principal) to build the list/detail query. It may be def
or async def; it builds a query and should not perform database I/O. When
reads are public, principal is None; when the list action has an access
policy, it is the
authenticated Caller. Apply tenant or visibility filters here. owner is an
independent write safeguard, not read authorization. Writes are also
constrained by this query, primary key and owner column, including in the
mutation statement.
Override to_schema(item) with def or async def for a response shape that
needs loaded relations; relations are never loaded implicitly. Override
written_queryset(principal) with either form to load response relations after
a successful write, independently of filters that might hide the changed row
from subsequent list requests.
Generated write routes call these overridable hooks inside their transaction.
Each hook may be a normal def or async def. Sync hooks run on Hinoki's
bounded worker executor, where synchronous ORM methods are available; async
hooks run on the event loop and should use the async ORM methods. This applies
to get_queryset, written_queryset, to_schema, store, change and
remove.
For a synchronous hook, use synchronous ORM methods and return the model:
def slug_for(title: str) -> str:
return title.casefold().replace(" ", "-")
class Posts(API):
def store(self, values: dict[str, Any], principal: Caller[Any]) -> Post:
values["slug"] = slug_for(str(values["title"]))
return Post.create(**values)
An async hook uses the async ORM method:
async def store(self, values: dict[str, Any], principal: Caller[Any]) -> Post:
values["slug"] = slug_for(str(values["title"]))
return await Post.acreate(**values)
A sync override uses Post.create(**values); it should not call async ORM
methods or return an un-awaited coroutine.
change(item, scoped_queryset, values, principal) and
remove(item, scoped_queryset, principal) receive the target and the
query already limited by visibility, key and ownership. Call super() to keep
the default scoped database mutation. Hooks may use transactional database
operations; they do not run after commit, so do not send mail or publish
external events directly from them. Hooks are trusted application code: do not
bypass the supplied scoped queryset with an unscoped model write or raw SQL.
Hinoki checks the persisted item after create/update for model identity and
server-assigned field invariants, but cannot sandbox arbitrary hook side effects.
Replace a generated action with a same-name decorated method, or use
replaces=Crud.CREATE (or another Crud member) on a differently named route.
An undecorated method named list, retrieve, create, update or delete
intentionally shadows and removes that generated route. A differently named
method without replaces= is a separate route and may collide by path/method;
route registration reports duplicates.
Security and validation¶
Set owner = "author_id" to assign that column from the authenticated caller
on create and constrain update/delete. identity_key extracts the owner value
from Caller.user; its default reads .id. assign maps additional
server-owned columns to functions of the caller's user object. Client schemas
cannot accept server-assigned fields. Generated writes require an access
policy even when owner is configured.
With ClaimsJWTAuth there is no user object, so use
identity_key = caller_id (from hinoki.resources): the owner value is then the
caller's Caller.id (the token sub). A foreign update or delete answers 403
and a missing row 404, as without the native lane. This is the only owner
declaration that can run natively; see
authentication.
At class declaration Hinoki rejects abstract models, unknown schema fields,
unsafe nullable fields, missing required create values, update schemas that
can overwrite omitted fields, primary-key updates, unknown assigned columns,
and incompatible derived schemas. only= and exclude= schemas remain
subject to these same checks.
A stored row that the read= schema refuses (for example a max_length that the data exceeds) is a server-side fault, not a client error: the action answers 500 and the response does not repeat the stored values; the server-side error names the model, the read schema, the field and the code. Client input that fails a create or update schema still answers 422.
Model hooks and Kiso¶
Generated create and PATCH update write through the model, so its lifecycle hooks run: create calls acreate, and update saves the item with the scoped query's conditions in its UPDATE, so a row that left the caller's scope since it was read is refused (403/404) exactly as on the unhooked path. A model that defines any of before_save, before_create, after_create or after_save is not eligible for the native create and update routes, which execute without Python model code; they use the Python lane, while its list, retrieve and delete routes stay native. Deleting does not run hooks.
OpenAPI and inspection¶
To inspect routes without starting the server:
cd examples
uv run --project .. hinoki routes blog.main:create_app --path /posts
Generated routes include schemas, access policies, status codes and pagination in the OpenAPI document. See the CRUD API reference.
Generated CRUD suits ordinary model-backed operations. Prefer a handwritten action when a workflow has distinct state transitions, error semantics or side-effects beyond the single model mutation.