GuidesEndpoints
Register routes¶
An application serves the routes that hinoki.toml points to. The project and each app keep their routes in a routes.py that exports a list, and notes/main.py includes them all with manifest_routes().
From the manifest to the application¶
# hinoki.toml
[project]
application = "notes.main:app"
routes = "notes.routes:routes" # the project's own routes
[[apps]]
name = "billing"
models = "notes.apps.billing.models"
migrations = "notes.apps.billing.migrations"
routes = "notes.apps.billing.routes:routes"
prefix = "/billing" # "/<name>" when omitted
requires = []
# notes/main.py
from hinoki import Hinoki
from hinoki.project import manifest_routes
from notes.rules import project_rules
from notes.settings import ProjectSettings
app = Hinoki(
settings=ProjectSettings,
include=manifest_routes(),
title="Notes",
openapi_url="/openapi.json",
docs_url="/docs",
rules=project_rules,
)
manifest_routes() finds hinoki.toml from the calling file's directory upwards and returns, in order:
- the project's
routeslist, at its own paths; - each app's
routeslist under the app'sprefix, apps in dependency order (requires).
An app without a routes key, or with an empty list, adds nothing. Outside a project it raises ProjectError. hinoki app create billing writes the routes.py and the manifest keys; hinoki app create billing --prefix /payments chooses another prefix. hinoki app list prints each app with its routes and prefix.
One place for each prefix¶
| Segment | Declared by | Example |
|---|---|---|
| The app | prefix in hinoki.toml |
/billing |
| A version inside the app | Mount in routes.py |
/v2 |
| The resource | RouteGroup(...) or API, path=... |
/invoices |
Write each segment once. Paths in code are relative to the app, so moving an app is a one-line change in hinoki.toml.
Versions with Mount¶
Mount(prefix, *items) prepends its prefix to everything it holds. Use it inside routes.py when one app serves several versions:
# notes/apps/billing/routes.py
from hinoki import Includable, Mount
from . import v1, v2
routes: list[Includable] = [
Mount("/v1", v1.routes),
Mount("/v2", v2.routes),
]
The result is /billing/v1/invoices and /billing/v2/invoices. Mounts nest, and their prefixes join from the outside in. A prefix starts with / and does not end with one, and a mount holds at least one item. Mounting changes the path only: access, errors and transactions stay as declared.
What include accepts¶
Includable is the type of every item a routes list may hold:
| Item | Example |
|---|---|
| A decorated function | health |
A RouteGroup |
invoices |
An API class, including a @crud class |
Invoices |
A crud(...) value |
crud(Invoice, path="/invoices", read=InvoiceOut) |
A Mount |
Mount("/v1", v1.routes) |
An object with an api() method |
the admin |
| A list or tuple of these | v1.routes |
Nested lists are spread in place, in the order you wrote them. Annotate each list as routes: list[Includable] so the type checker rejects anything else; a module passed instead of its list is refused with a hint to export a list.
The application module¶
Declare app once, at module level, in the module that project.application names. Importing it reads the settings and builds declarations; nothing connects until a worker starts, so commands, servers and tests import the same object. A factory target (module:create_app) is still accepted by the commands, for code that must build the application from runtime values.
Routes for tests and options¶
To serve a subset, or the same routes with other settings, build another Hinoki with an explicit include=:
# tests/billingroutestest.py
from hinoki import Hinoki, Mount
from notes.apps.billing.routes import routes
app = Hinoki(include=[Mount("/billing", routes)])
include=[] is an empty application. To add routes that exist only when a setting is on, call app.include(...) in the application module before it serves:
# notes/main.py (continued)
from hinoki import Mount
from notes.apps.billing.exports import exports
if app.settings.billing_exports:
app.include(Mount("/billing", exports))
Inspect the map¶
hinoki routes
hinoki routes --path /billing --method POST
hinoki routes --format json
Rows are sorted by path, then method, and show the effective access policy and the handler. --lanes adds the serving lane of each route. See list routes with routes for every option.
Errors and edge cases¶
Everything below fails when the application is built, before it serves a request:
| Message | Cause |
|---|---|
cannot load the routes of app 'billing' (notes.apps.billing.routes:routes): … |
The module or attribute in hinoki.toml does not import |
the routes of app 'billing' (…) must be a list of routes |
routes is a single item, not a list or tuple |
RegistrationError naming an action |
Two routes reach the same method and path after prefixes join |
RegistrationError: application is already serving; it is frozen |
app.include(...) after the server started |
An include call registers all its items or none of them.