BoscaDeveloper Documentation

Routes

HTTP endpoints with @RouteController, Route<T>, APIRoute<T>, SSERoute<T>, Page, and ServerCall.

Route Types

Base ClassResponseUse Case
Route<T>JSON-serialized TStandard REST endpoints
APIRoute<T>JSON with structured errorsPublic API endpoints
SSERoute<T>Server-Sent Events streamReal-time streaming (AI chat, progress)
PageServer-rendered HTML (JTE)Web pages

Defining a Route

kotlin

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

ParameterDefaultPurpose
path—URL pattern
methodGETGET, POST, PUT, DELETE, PATCH, HEAD
authenticationOPTIONALNONE, 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.

kotlin

ServerCall

Reading requests
Writing responses

Path Parameters

kotlin

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.