| name | api-add-route |
| description | Use when adding or changing an HTTP route under services/api. Walks the exact steps so the new route follows Helpline's gateway conventions. |
| paths | services/api/** |
Adding an API route
Activates for work in services/api. Follow these steps in order.
- Write the handler in the matching module (
tickets.py for ticket
routes, a new module for a new noun). Signature is
(request: dict) -> dict.
- Validate inputs first. Missing/!bad input raises
ValidationError —
never return an error dict by hand.
- Do no business logic here. Call a repo (
packages/db) or another
service. The handler only orchestrates and shapes the response.
- Register the route in
routes.py inside build_app() —
app.route("METHOD /path", handler). A route not registered there does not
exist.
- Add a test in
tests/ that builds the app and dispatches the route.
Full checklist with a worked example: references/route-checklist.md.