Routes and HTTP Architecture · The Book

Routes are the public edge of a Carrier service. They define how callers interact with business capabilities over HTTP. A route is not just a function with a URL — it is part of the enterprise contract.

A Real Route in the Booking Service

The route below comes from the booking-service. It is an excellent template for thin route design: parameter shape, role protection, idempotency, and a single delegation to an action — all with the workflow logic kept where it belongs.

excerpt

route POST "/slots/{id}/lock" protect StaffAuth roles [scheduler] idempotent -> AppointmentSlot {
params {
id: UUID
}
 
handler {
return lock_slot_for_review(params.id)
}
}

The route declares its own HTTP semantics — method, path, role, idempotency key behavior, and response type — and then delegates. There are no transactions in the route. There is no business decision in the route. This is what thin means in practice.

Custom Routes vs CRUD Routes

Use custom route declarations for workflows, reporting, commands, and non-standard API shapes — submitting an intake form, approving a claim, scheduling an appointment, closing an encounter. Use crud when standard resource behavior is actually the right model. CRUD works well for simple resources with conventional create, read, update, and delete semantics. It is less suitable for domain workflows where state transitions, policy checks, audit requirements, or side effects matter. Be cautious when everything becomes CRUD — many business operations are not generic updates.

Edge Semantics

Routes own edge semantics: method, path, input, output, authentication requirement, and HTTP-level behavior. That includes whether an operation is idempotent, whether it returns a created resource or an operation result, whether it exposes a list or a search workflow, and how errors are represented. These choices matter because consumers build against them.

Keeping Routes Thin

A thin route translates HTTP into a domain operation. It should not become the place where business rules accumulate. If the route is making decisions about workflow state, authorization details, persistence, or transaction sequencing, the design should be reconsidered. Thin routes make services easier to review, test, document, and govern. They also make OpenAPI output a better reflection of the actual API surface.

Part Three

Enterprise Concerns

Identity, policy, governance, and regulated domains

❦