Tutorial
4. Endpoints¶
The HTTP layer maps requests to operations and results to responses. It holds no business rule and no SQL.
First, who may call. A bearer token resolves to a Member, and the policy
names the permission that every task action requires:
# tracker/security.py
from hinoki import Access, BearerAuth, Caller, Permission
from .models import Member
class TrackerPermission(Permission):
USE = "tasks:use"
class MemberTokens(BearerAuth[Member]):
async def resolve_token(self, token: str) -> Caller[Member] | None:
member = await Member.aget_or_none(token=token)
if member is None:
return None
return Caller(
id=str(member.id), user=member, permissions={TrackerPermission.USE}
)
member_only = Access(auth=MemberTokens(), permissions=[TrackerPermission.USE])
Then the actions. A public health check stands alone; a RouteGroup states
the path prefix, the policy and the transaction once for the tasks:
# tracker/api.py
from uuid import UUID
from hinoki import Caller, RouteGroup, Schema, errors, http
from hinoki.pagination import Page, PageNumberPagination, PageParams
from . import operations
from .errors import DoneTasksAreKept, TaskAlreadyDone
from .models import Member
from .schemas import TaskIn, TaskOut
from .security import member_only
class Health(Schema):
status: str
@http.get("/health")
def health() -> Health:
return Health(status="ok")
tasks = RouteGroup("/tasks", access=member_only, atomic=True)
@tasks.get("/", pagination=PageNumberPagination(page_size=10, max_page_size=50))
async def list_tasks(page: PageParams, caller: Caller[Member]) -> Page[TaskOut]:
"""Your tasks, newest first."""
return (await operations.list_tasks(caller.user.id, page)).map(TaskOut.from_model)
@tasks.post("/", status=201)
async def create_task(data: TaskIn, caller: Caller[Member]) -> TaskOut:
return TaskOut.from_model(await operations.create_task(caller.user.id, data))
# tracker/api.py (continued)
@tasks.post("/{task_id}/complete", errors=(errors.NotFound, TaskAlreadyDone))
async def complete_task(task_id: UUID, caller: Caller[Member]) -> TaskOut:
return TaskOut.from_model(await operations.complete_task(caller.user.id, task_id))
@tasks.delete("/{task_id}", status=204, errors=(errors.NotFound, DoneTasksAreKept))
async def delete_task(task_id: UUID, caller: Caller[Member]) -> None:
await operations.delete_task(caller.user.id, task_id)
access=names a reusable policy. Actions are public unless they name one, so protect on purpose; a rule in the next chapter enforces it.atomic=Trueruns each write in a transaction. It commits after the response is encoded and rolls back before an error becomes HTTP.errors=(...)declares what an action may raise. The OpenAPI document, the MCP tool description and the strict test client all read it.caller: Caller[Member]is the authenticated caller, typed:caller.useris yourMember.TaskOut.from_model(...)converts a row into the response. A handler never returns a model; lists and pages use.map(...).
Declare request: Request as the first parameter only when you need headers,
cookies or the raw body. File uploads are covered in
upload files.
Register the routes¶
In a project, routes.py lists the groups and hinoki.toml mounts them
(chapter 8). Tracker's main.py includes tasks directly,
because examples/ hosts three applications (chapter 6).
Recap¶
- A
RouteGroupstates access, transactions and the prefix once. - Handlers call operations and convert rows with
from_model. - Every error an action raises is declared.
Next: 5. Rules. In the guides: function-based APIs and class-based APIs.