GuidesEndpoints
Class-based APIs¶
A class-based API is a subclass of API whose methods carry the same @http.* decorators as functions. A class adds a path prefix, inheritance and, with @crud(...), generated routes with hooks. For ordinary endpoints prefer functions and a RouteGroup, which also states access, transactions and errors once.
When to use it¶
| Use a class for | Example |
|---|---|
| Generated CRUD plus hooks or extra actions | @crud(Invoice, ...) with get_queryset and a pay action |
| Actions that several resources inherit or override | A base API with a counts action, reused under two prefixes |
| A resource you ship for other projects to include | The admin |
A class that only puts three functions under a prefix gains nothing over a RouteGroup, and each of its actions must repeat access=, atomic= and errors=.
A plain class¶
# notes/apps/billing/reports.py
from hinoki import API, Schema, http
from notes.security import billing_staff
from .models import Invoice
class InvoiceCounts(Schema):
open: int
paid: int
class Reports(API, path="/reports"):
@http.get("/counts", access=billing_staff)
async def counts(self) -> InvoiceCounts:
return InvoiceCounts(
open=await Invoice.filter(paid=False).acount(),
paid=await Invoice.filter(paid=True).acount(),
)
path= is the class prefix; each action's path is relative to it, so this action is served at /billing/reports/counts once Reports is in routes.py.
Inherit and override¶
A subclass inherits every routed method. Members are resolved by name, most derived first:
# notes/apps/billing/reports.py (continued)
class ArchiveReports(Reports, path="/archive"): # /archive/counts, own prefix
pass
class PublicReports(Reports): # inherits path="/reports"
def counts(self) -> None: # redefined without a decorator: no route
return None
| In the subclass | Result |
|---|---|
| Nothing | The route is inherited, under the subclass's path= or the inherited one |
| The same name with a decorator | Replaces the inherited route |
| The same name without a decorator | Drops the inherited route |
Include only the classes you serve. A base and a subclass with the same prefix are two copies of every inherited route, and the application refuses the second.
Generated CRUD with hooks¶
@crud(...) generates list and retrieve, plus the writes you give a schema for, on a class whose only base is API. Hooks change what the generated actions do; any other decorated method is a handwritten action:
# notes/apps/billing/api.py
from typing import Any
from uuid import UUID
from hinoki import API, Caller, crud, errors, http
from hinoki.orm import QuerySet
from notes.security import billing_staff
from .models import Invoice
from .schemas import InvoiceIn, InvoiceOut
class InvoiceAlreadyPaid(errors.Conflict):
code = "invoice_already_paid"
message = "The invoice is already paid."
@crud(
Invoice, path="/invoices", read=InvoiceOut, create=InvoiceIn, access=billing_staff
)
class Invoices(API):
def get_queryset(self, principal: Caller[Any] | None) -> QuerySet[Invoice]:
return Invoice.all().order_by("reference")
@http.post(
"/{item_id}/pay",
access=billing_staff,
atomic=True,
errors=(errors.NotFound, InvoiceAlreadyPaid),
)
async def pay(self, item_id: UUID) -> InvoiceOut:
changed = await Invoice.aupdate_where(
{"id": item_id, "paid": False}, {"paid": True}
)
if not changed:
await Invoice.aget(id=item_id) # 404 when it does not exist
raise InvoiceAlreadyPaid()
return InvoiceOut.from_model(changed[0])
# notes/apps/billing/routes.py
from hinoki import Includable
from .api import Invoices
routes: list[Includable] = [Invoices]
| Route | Source | Access |
|---|---|---|
GET /billing/invoices |
generated list (paginated) |
billing_staff |
GET /billing/invoices/{item_id} |
generated retrieve |
billing_staff |
POST /billing/invoices |
generated create (create=InvoiceIn, atomic) |
billing_staff |
POST /billing/invoices/{item_id}/pay |
handwritten pay |
its own access= |
The access= of crud(...) covers generated actions only; a handwritten method states its own. pay changes the row only if it is still unpaid, in one statement, so two concurrent calls cannot both succeed. Hooks, CrudAccess, owner= and every keyword are in Generate CRUD routes.
When a resource needs no code, crud(...) is a value, not a class:
# notes/apps/billing/routes.py
from hinoki import Includable, crud
from notes.security import billing_staff
from .models import Invoice
from .schemas import InvoiceIn, InvoiceOut
routes: list[Includable] = [
crud(
Invoice,
path="/invoices",
read=InvoiceOut,
create=InvoiceIn,
access=billing_staff,
),
]
One instance per request¶
Hinoki creates the class with no arguments for every request and calls the method on that instance. Keep self empty:
- Take request data as parameters:
request: Request,caller: Caller[Staff], path and body values. - Reach worker resources through a module, never through attributes set on
selfor on the class. - Do not define an
__init__that needs arguments. Hinoki refuses it when the class is included.
A class that keeps the stock constructor and sets no response_headers is eligible for the native handler lane like a function. hinoki routes --lanes shows the choice per route.
Best practices¶
- Use a class for
@crud, inheritance or a shipped resource, functions otherwise. - One base,
API. A@crudclass accepts no other base. Share configuration with a value (staff_crud = functools.partial(crud, access=billing_staff)) instead of a mixin. - State
access=,atomic=anderrors=on every handwritten action. The class carries a path only. - Scope writes in the statement (
aupdate_wherewith the conditions), not check-then-write. - Hooks build queries.
get_querysetdoes no I/O; load relations explicitly into_schemaorwritten_queryset. - Let
crudgenerate or omit, not compete. To writelistorretrieveyourself, passomit=("list",)and define a method with another name; to writecreateyourself, leavecreate=out.
Test it¶
# tests/invoicestest.py
from notes.apps.billing.api import Invoices
from notes.security import billing_staff
def test_invoice_routes() -> None:
routes = {(r.method, r.path): r for r in Invoices.routes()}
pay = routes["POST", "/invoices/{item_id}/pay"]
assert (pay.access, pay.atomic) == (billing_staff, True)
assert ("GET", "/invoices/{item_id}") in routes
Invoices.routes() lists the class routes with its own prefix, without an application. Request tests are the same as for functions: build Hinoki(include=[Mount("/billing", routes)]) and use ASGIClient (function-based APIs, testing).
Pitfalls¶
| Symptom | Cause | Fix |
|---|---|---|
RegistrationError: … is created without arguments per request |
An __init__ with required arguments |
Remove it; take values as parameters |
RegistrationError on a @staticmethod or @classmethod route |
Routes are instance methods | Drop the decorator and keep self |
RegistrationError: Invoices: a crud(...) class has exactly one base, API |
A mixin or another base | Share a functools.partial(crud, ...) or Access values |
RegistrationError naming create (or list, …) |
A method named like an action crud generates |
Rename it, or stop generating that action (omit=, no create=) |
RegistrationError: … is declared by two classes (/a and /b) |
Two different classes (often two crud(...) values for one model in one module) give an action the same qualified name |
Rename one class, or pass crud(..., name="ArchiveCrud") |
| A handwritten action is public | crud(access=...) covers generated actions only |
Add access= to its decorator |
| A route vanished in a subclass | The method was redefined without a decorator | Re-declare it with its decorator |
Old code uses replaces=Crud.CREATE |
An older way to swap a generated action | Leave create= out and name the method freely; replaces= still works while create= is given |