0
# Routing System
1

2
Type-safe routing DSL for defining HTTP endpoints and handling requests with Ktor server.
3

4
## Capabilities
5

6
### Routing Installation
7

8
Install and configure the routing system in your Ktor application.
9

10
```kotlin { .api }
11
/**
12
 * Install routing in the application
13
 * @param configuration Routing configuration block
14
 * @return Routing instance
15
 */
16
fun Application.routing(configuration: Routing.() -> Unit): Routing
17

18
/**
19
 * Install routing plugin in the application
20
 */
21
fun Application.install(plugin: Routing): Routing
22
```
23

24
**Usage Examples:**
25

26
```kotlin
27
import io.ktor.server.application.*
28
import io.ktor.server.routing.*
29
import io.ktor.server.response.*
30

31
fun Application.configureRouting() {
32
    routing {
33
        get("/") {
34
            call.respondText("Hello World!")
35
        }
36
        
37
        get("/users") {
38
            call.respondText("User list")
39
        }
40
    }
41
}
42
```
43

44
### Route Interface
45

46
Core routing interface providing the foundation for all routing operations.
47

48
```kotlin { .api }
49
/**
50
 * Core route interface
51
 */
52
interface Route {
53
    /**
54
     * Parent route or null if this is the root
55
     */
56
    val parent: Route?
57
    
58
    /**
59
     * Route selector for matching requests
60
     */
61
    val selector: RouteSelector
62
    
63
    /**
64
     * Development mode flag
65
     */
66
    val developmentMode: Boolean
67
    
68
    /**
69
     * Application environment
70
     */
71
    val environment: ApplicationEnvironment
72
    
73
    /**
74
     * Create a child route with the given selector
75
     */
76
    fun createChild(selector: RouteSelector): Route
77
    
78
    /**
79
     * Select routes matching the given context
80
     */
81
    fun select(context: RoutingResolveContext): RoutingResolveResult
82
}
83

84
/**
85
 * Root routing interface
86
 */
87
interface Routing : Route {
88
    /**
89
     * All registered routes
90
     */
91
    val allRoutes: List<Route>
92
}
93
```
94

95
### HTTP Method Routes
96

97
Route definitions for standard HTTP methods.
98

99
```kotlin { .api }
100
/**
101
 * Handle GET requests
102
 * @param path URL path pattern
103
 * @param body Request handler
104
 * @return Created route
105
 */
106
fun Route.get(
107
    path: String = "",
108
    body: suspend PipelineContext<Unit, ApplicationCall>.() -> Unit
109
): Route
110

111
/**
112
 * Handle POST requests
113
 * @param path URL path pattern
114
 * @param body Request handler
115
 * @return Created route
116
 */
117
fun Route.post(
118
    path: String = "",
119
    body: suspend PipelineContext<Unit, ApplicationCall>.() -> Unit
120
): Route
121

122
/**
123
 * Handle PUT requests
124
 * @param path URL path pattern
125
 * @param body Request handler
126
 * @return Created route
127
 */
128
fun Route.put(
129
    path: String = "",
130
    body: suspend PipelineContext<Unit, ApplicationCall>.() -> Unit
131
): Route
132

133
/**
134
 * Handle DELETE requests
135
 * @param path URL path pattern
136
 * @param body Request handler
137
 * @return Created route
138
 */
139
fun Route.delete(
140
    path: String = "",
141
    body: suspend PipelineContext<Unit, ApplicationCall>.() -> Unit
142
): Route
143

144
/**
145
 * Handle HEAD requests
146
 * @param path URL path pattern
147
 * @param body Request handler
148
 * @return Created route
149
 */
150
fun Route.head(
151
    path: String = "",
152
    body: suspend PipelineContext<Unit, ApplicationCall>.() -> Unit
153
): Route
154

155
/**
156
 * Handle OPTIONS requests
157
 * @param path URL path pattern
158
 * @param body Request handler
159
 * @return Created route
160
 */
161
fun Route.options(
162
    path: String = "",
163
    body: suspend PipelineContext<Unit, ApplicationCall>.() -> Unit
164
): Route
165

166
/**
167
 * Handle PATCH requests
168
 * @param path URL path pattern
169
 * @param body Request handler
170
 * @return Created route
171
 */
172
fun Route.patch(
173
    path: String = "",
174
    body: suspend PipelineContext<Unit, ApplicationCall>.() -> Unit
175
): Route
176
```
177

178
**Usage Examples:**
179

180
```kotlin
181
routing {
182
    // Basic routes
183
    get("/") { call.respondText("Home page") }
184
    post("/users") { call.respondText("Create user") }
185
    put("/users/{id}") { call.respondText("Update user ${call.parameters["id"]}") }
186
    delete("/users/{id}") { call.respondText("Delete user ${call.parameters["id"]}") }
187
    
188
    // Path parameters
189
    get("/users/{id}") {
190
        val userId = call.parameters["id"]
191
        call.respondText("User: $userId")
192
    }
193
    
194
    // Optional parameters
195
    get("/posts/{id?}") {
196
        val postId = call.parameters["id"]
197
        if (postId != null) {
198
            call.respondText("Post: $postId")
199
        } else {
200
            call.respondText("All posts")
201
        }
202
    }
203
}
204
```
205

206
### Route Groups and Nesting
207

208
Organize routes into logical groups with shared configuration.
209

210
```kotlin { .api }
211
/**
212
 * Create a route group with common path prefix
213
 * @param path Common path prefix
214
 * @param build Route configuration block
215
 * @return Created route
216
 */
217
fun Route.route(
218
    path: String,
219
    build: Route.() -> Unit
220
): Route
221

222
/**
223
 * Create a route group with HTTP method selector
224
 * @param method HTTP method to match
225
 * @param build Route configuration block
226
 * @return Created route
227
 */
228
fun Route.method(
229
    method: HttpMethod,
230
    build: Route.() -> Unit
231
): Route
232

233
/**
234
 * Create a route group with host selector
235
 * @param host Host pattern to match
236
 * @param build Route configuration block
237
 * @return Created route
238
 */
239
fun Route.host(
240
    host: String,
241
    build: Route.() -> Unit
242
): Route
243

244
/**
245
 * Create a route group with port selector
246
 * @param port Port number to match
247
 * @param build Route configuration block
248
 * @return Created route
249
 */
250
fun Route.port(
251
    port: Int,
252
    build: Route.() -> Unit
253
): Route
254
```
255

256
**Usage Examples:**
257

258
```kotlin
259
routing {
260
    // Path-based grouping
261
    route("/api") {
262
        route("/v1") {
263
            get("/users") { call.respondText("V1 Users") }
264
            get("/posts") { call.respondText("V1 Posts") }
265
        }
266
        
267
        route("/v2") {
268
            get("/users") { call.respondText("V2 Users") }
269
            get("/posts") { call.respondText("V2 Posts") }
270
        }
271
    }
272
    
273
    // Host-based routing
274
    host("api.example.com") {
275
        get("/") { call.respondText("API Server") }
276
    }
277
    
278
    host("admin.example.com") {
279
        get("/") { call.respondText("Admin Panel") }
280
    }
281
    
282
    // Port-based routing
283
    port(8080) {
284
        get("/") { call.respondText("Public API") }
285
    usrs
286
    
287
    port(8081) {
288
        get("/") { call.respondText("Admin API") }
289
    }
290
}
291
```
292

293
### Route Selectors
294

295
Flexible route matching system for complex routing scenarios.
296

297
```kotlin { .api }
298
/**
299
 * Base interface for route selectors
300
 */
301
sealed class RouteSelector {
302
    /**
303
     * Evaluate if this selector matches the given context
304
     */
305
    abstract fun evaluate(context: RoutingResolveContext, segmentIndex: Int): RouteSelectorEvaluation
306
}
307

308
/**
309
 * Path segment selector for literal path matching
310
 */
311
data class PathSegmentConstantRouteSelector(val value: String) : RouteSelector()
312

313
/**
314
 * Path parameter selector for capturing path variables
315
 */
316
data class PathSegmentParameterRouteSelector(
317
    val name: String,
318
    val prefix: String = "",
319
    val suffix: String = ""
320
) : RouteSelector()
321

322
/**
323
 * Wildcard selector for capturing remaining path segments
324
 */
325
data class PathSegmentWildcardRouteSelector(val name: String) : RouteSelector()
326

327
/**
328
 * Optional path segment selector
329
 */
330
data class PathSegmentOptionalParameterRouteSelector(val name: String) : RouteSelector()
331

332
/**
333
 * HTTP method selector
334
 */
335
data class HttpMethodRouteSelector(val method: HttpMethod) : RouteSelector()
336

337
/**
338
 * Accept header selector for content negotiation
339
 */
340
data class HttpAcceptRouteSelector(val contentType: ContentType) : RouteSelector()
341
```
342

343
### Route Resolution
344

345
Route matching and resolution system.
346

347
```kotlin { .api }
348
/**
349
 * Context for route resolution
350
 */
351
class RoutingResolveContext(
352
    val routing: Route,
353
    val call: ApplicationCall,
354
    val parameters: ParametersBuilder = ParametersBuilder()
355
) {
356
    val segments: List<String>
357
    val headers: Headers
358
    val method: HttpMethod
359
}
360

361
/**
362
 * Result of route resolution
363
 */
364
sealed class RoutingResolveResult {
365
    /**
366
     * Successful route resolution
367
     */
368
    data class Success(val route: Route, val parameters: Parameters) : RoutingResolveResult()
369
    
370
    /**
371
     * Failed route resolution
372
     */
373
    object Failure : RoutingResolveResult()
374
}
375

376
/**
377
 * Route evaluation result
378
 */
379
sealed class RouteSelectorEvaluation {
380
    /**
381
     * Successful evaluation
382
     */
383
    data class Success(val segmentIncrement: Int) : RouteSelectorEvaluation()
384
    
385
    /**
386
     * Failed evaluation
387
     */
388
    object Failed : RouteSelectorEvaluation()
389
    
390
    /**
391
     * Evaluation with quality factor
392
     */
393
    data class SuccessWithQuality(val segmentIncrement: Int, val quality: Double) : RouteSelectorEvaluation()
394
}
395
```
396

397
### Authenticated Routes
398

399
Integration with authentication system for protected routes.
400

401
```kotlin { .api }
402
/**
403
 * Create authenticated routes that require valid authentication
404
 * @param configurations Authentication configurations to require
405
 * @param optional Make authentication optional
406
 * @param build Route configuration block
407
 * @return Created route
408
 */
409
fun Route.authenticate(
410
    vararg configurations: String? = arrayOf<String?>(null),
411
    optional: Boolean = false,
412
    build: Route.() -> Unit
413
): Route
414
```
415

416
**Usage Examples:**
417

418
```kotlin
419
routing {
420
    // Public routes
421
    get("/") { call.respondText("Public page") }
422
    post("/login") { /* handle login */ }
423
    
424
    // Authenticated routes
425
    authenticate {
426
        get("/profile") { call.respondText("User profile") }
427
        post("/logout") { /* handle logout */ }
428
        
429
        // Admin-only routes
430
        authenticate("admin") {
431
            get("/admin") { call.respondText("Admin panel") }
432
            delete("/users/{id}") { /* delete user */ }
433
        }
434
    }
435
    
436
    // Optional authentication
437
    authenticate(optional = true) {
438
        get("/posts") {
439
            val user = call.principal<UserPrincipal>()
440
            if (user != null) {
441
                call.respondText("Posts for ${user.name}")
442
            } else {
443
                call.respondText("Public posts")
444
            }
445
        }
446
    }
447
}
448
```