Routes
HTTP endpoints with @RouteController, Route<T>, APIRoute<T>, SSERoute<T>, Page, and ServerCall.
Route Types
| Base Class | Response | Use Case |
|---|---|---|
Route<T> | JSON-serialized T | Standard REST endpoints |
APIRoute<T> | JSON with structured errors | Public API endpoints |
SSERoute<T> | Server-Sent Events stream | Real-time streaming (AI chat, progress) |
Page | Server-rendered HTML (JTE) | Web pages |
Defining a Route
This excerpt uses PasskeyInfo from the existing passkey routes. The complete route and response model are in bosca-core/security/src/main/kotlin/bosca/security/routes/passkey/PasskeyList.kt. Import routing types from bosca.routes and bosca.routes.annotations, and HTTP types from bosca.server.
@RouteController
| Parameter | Default | Purpose |
|---|---|---|
path | — | URL pattern |
method | GET | GET, POST, PUT, DELETE, PATCH, HEAD |
authentication | OPTIONAL | NONE, REQUIRED, OPTIONAL |
Return a value with an explicit serializer for JSON model responses. Returning null without a response produces 404; returning Unit without a response produces 204.
SSE Routes
This illustrative route sends two status events and closes the stream. Import SSE types from bosca.server.sse.
ServerCall
Path Parameters
Authentication: Routes vs. GraphQL
Routes declare auth at the route level (NONE/REQUIRED/OPTIONAL). GraphQL injects a request authentication context into resolvers; protected fields explicitly use permission or group evaluators.
Both use the shared authentication providers. Route authentication still needs domain authorization checks before accessing protected records.