pre-alpha

Tutorial

Tutorial

implemented Updated November 20, 2026 1 min read

Follow the Tracker, an API where members keep their own tasks, one layer per chapter. Each chapter walks through files of the checked-in example in examples/tracker and runs its commands, so every step runs as shown. Chapter 8 then adds an app to your own project.

Chapter It covers You learn
1. Models tables, an index, a default order models and migrations
2. Schemas what clients send and receive strict validation, derived schemas
3. Operations the business rules ownership inside the statement
4. Endpoints the HTTP layer access, transactions, declared errors
5. Rules checks that keep the layers apart hinoki check
6. Run and test it settings, a server, tests hinoki dev, the test client
7. Validate input normalizers and checks field and cross-field errors
8. Projects and apps an app in your own project hinoki app create, planned migrations

Chapters 1–6 cover the Tracker. Chapter 7 uses standalone examples, and chapter 8 continues the project from the Quick start.

The shape you end with:

api.py          HTTP: shapes, status codes, access, transactions
   ↓
operations.py   business rules: plain async functions, no HTTP types
   ↓
models.py       tables and relations

Before you start

Install Hinoki. Chapters 1–6 run in the checkout's examples/ directory:

cd examples

That directory hosts three applications (Notes, Tracker and Blog) under one hinoki.toml, so server and check commands name the application, such as uv run hinoki check tracker.main:app. Without it, hinoki check here checks the directory's own project.app:app, which declares no rules, and reports 0 rule(s). In your own project the commands take no target.