ktor-server-core/io.ktor.server.routing

Package-level declarations

Types

data class AndRouteSelector(val first: RouteSelector, val second: RouteSelector) : RouteSelector, CompositeRouteSelector

Evaluates a route as a result of the AND operation using two other selectors.

CompositeRouteSelector

interface CompositeRouteSelector

Exposes child selectors composing this selector (e.g., Or/And).

ConstantParameterRouteSelector

data class ConstantParameterRouteSelector(val name: String, val value: String) : RouteSelector

Evaluates a route against a constant query parameter value.

HostRouteSelector

data class HostRouteSelector(val hostList: List<String>, val hostPatterns: List<Regex>, val portsList: List<Int>) : RouteSelector

Evaluates a route against a request's host and port.

HttpAcceptRouteSelector

data class HttpAcceptRouteSelector(val contentType: ContentType) : RouteSelector

Evaluates a route against a Content-Type in the HttpHeaders.Accept request header.

HttpHeaderRouteSelector

data class HttpHeaderRouteSelector(val name: String, val value: String) : RouteSelector, RouteParameterComponent

Evaluates a route against a header in the request.

HttpMethodRouteSelector

data class HttpMethodRouteSelector(val method: HttpMethod) : RouteSelector

Evaluates a route against an HttpMethod.

HttpMultiAcceptRouteSelector

data class HttpMultiAcceptRouteSelector(val contentTypes: List<ContentType>) : RouteSelector

Evaluates a route against a Content-Type in the HttpHeaders.Accept request header.

LocalPortRouteSelector

data class LocalPortRouteSelector(val port: Int) : RouteSelector

Evaluates a route against the port on which a call is received.

OpenApiRoutePathFormat

object OpenApiRoutePathFormat : RoutePathFormat

A RoutePathFormat that uses OpenAPI path formatting rules.

OptionalParameterRouteSelector

data class OptionalParameterRouteSelector(val name: String) : RouteSelector, RouteParameterComponent

Evaluates a route against an optional query parameter value and captures its value, if found.

OrRouteSelector

data class OrRouteSelector(val first: RouteSelector, val second: RouteSelector) : RouteSelector, CompositeRouteSelector

Evaluates a route as a result of the OR operation using two other selectors.

ParameterRouteSelector

data class ParameterRouteSelector(val name: String) : RouteSelector, RouteParameterComponent

Evaluates a route against a query parameter value and captures its value.

PathSegmentConstantRouteSelector

data class PathSegmentConstantRouteSelector(val value: String) : RouteSelector, RoutePathComponent

Evaluates a route against a constant path segment.

PathSegmentOptionalParameterRouteSelector

data class PathSegmentOptionalParameterRouteSelector(val name: String, val prefix: String? = null, val suffix: String? = null) : RouteSelector, RoutePathComponent, RouteParameterComponent

Evaluates a route against an optional parameter path segment and captures its value, if any.

PathSegmentParameterRouteSelector

data class PathSegmentParameterRouteSelector(val name: String, val prefix: String? = null, val suffix: String? = null) : RouteSelector, RoutePathComponent, RouteParameterComponent

Evaluates a route against a parameter path segment and captures its value.

PathSegmentRegexRouteSelector

class PathSegmentRegexRouteSelector(val regex: Regex) : RouteSelector, RoutePathComponent

A route selector that matches a segment of the path against a specified regular expression regex. This selector allows flexible matching of URI path segments by using regex patterns.

PathSegmentSelectorBuilder

object PathSegmentSelectorBuilder

A helper object for building instances of RouteSelector from path segments.

PathSegmentTailcardRouteSelector

data class PathSegmentTailcardRouteSelector(val name: String = "", val prefix: String = "") : RouteSelector, RoutePathComponent

Evaluates a route against any number of trailing path segments, and captures their values.

PathSegmentWildcardRouteSelector

object PathSegmentWildcardRouteSelector : RouteSelector, RoutePathComponent

Evaluates a route against any single path segment.

RootRouteSelector

class RootRouteSelector(rootPath: String = "") : RouteSelector, RoutePathComponent

A selector for a routing root.

Route

interface Route : TreeLike<Route>

A builder for a routing tree.

RouteParameterComponent

interface RouteParameterComponent

Exposes the parameter name contributed by this selector (query, header, or path).

RoutePathComponent

sealed interface RoutePathComponent

Exposes a textual representation of the path fragment contributed by this selector. Used for tooling (e.g., documentation generation).

RoutePathFormat

interface RoutePathFormat

Common interface for formatting standard route path components.

RouteSelector

abstract class RouteSelector

Serves as the base type for routing selectors.

RouteSelectorEvaluation

sealed class RouteSelectorEvaluation

A result of a route evaluation against a call.

Routing

interface Routing : Route

A builder for a routing tree root.

RoutingCall

class RoutingCall : ApplicationCall

A single act of communication between a client and server that is handled in RoutingRoot.

RoutingContext

class RoutingContext(val call: RoutingCall)

The context of a RoutingHandler that is used to handle a RoutingCall.

RoutingHandler

typealias RoutingHandler = suspend RoutingContext.() -> Unit

A function that handles a RoutingCall.

RoutingNode

open class RoutingNode(val parent: RoutingNode?, val selector: RouteSelector, developmentMode: Boolean = false, environment: ApplicationEnvironment) : ApplicationCallPipeline, Route

Describes a node in a routing tree.

RoutingPath

class RoutingPath

A parsed routing path. Consist of number of segments parts.

RoutingPathSegment

data class RoutingPathSegment(val value: String, val kind: RoutingPathSegmentKind)

A single routing path segment.

RoutingPathSegmentKind

enum RoutingPathSegmentKind : Enum<RoutingPathSegmentKind>

Possible routing path segment kinds.

RoutingPipelineCall

class RoutingPipelineCall(val engineCall: PipelineCall, val route: RoutingNode, val coroutineContext: CoroutineContext, receivePipeline: ApplicationReceivePipeline, responsePipeline: ApplicationSendPipeline, val pathParameters: Parameters) : PipelineCall, CoroutineScope

An application call handled by RoutingRoot.

RoutingPipelineRequest

class RoutingPipelineRequest(val call: RoutingPipelineCall, val pipeline: ApplicationReceivePipeline, val engineRequest: PipelineRequest) : PipelineRequest

An application request handled by RoutingRoot.

RoutingPipelineResponse

class RoutingPipelineResponse(val call: RoutingPipelineCall, val pipeline: ApplicationSendPipeline, val engineResponse: PipelineResponse) : PipelineResponse

An application response handled by RoutingRoot.

RoutingRequest

class RoutingRequest : ApplicationRequest

A client's request that can be handled in RoutingRoot. To learn how to handle incoming requests, see Handling requests.

RoutingResolveContext

class RoutingResolveContext(val routing: RoutingNode, val call: PipelineCall, tracers: List<(RoutingResolveTrace) -> Unit>)

Represents a context in which routing resolution is being performed

RoutingResolveResult

sealed class RoutingResolveResult

Represents a result of routing resolution.

RoutingResolveTrace

class RoutingResolveTrace(val call: PipelineCall, val segments: List<String>)

Represents the trace of routing resolution process for diagnostics.

RoutingResolveTraceEntry

open class RoutingResolveTraceEntry(val route: RoutingNode, val segmentIndex: Int, var result: RoutingResolveResult? = null)

Represents a single entry in the RoutingResolveTrace.

RoutingResponse

class RoutingResponse : ApplicationResponse

A server's response that can be used to respond in RoutingRoot. To learn how to send responses inside route handlers, see Sending responses.

RoutingRoot

class RoutingRoot(val application: Application) : RoutingNode, Routing

A root routing node of an Application. You can learn more about routing in Ktor from Routing.

TrailingSlashRouteSelector

object TrailingSlashRouteSelector : RouteSelector, RoutePathComponent

Evaluates a route against a single trailing slash.

Properties

application

val Route.application: Application

Gets an Application for this RoutingNode by scanning the hierarchy to the root.

IgnoreTrailingSlash

val IgnoreTrailingSlash: ApplicationPlugin<Unit>

A plugin that enables ignoring a trailing slash when resolving URLs.

path

val Route.path: String

String representation of the path matched by this route.

RoutingFailureStatusCode

val RoutingFailureStatusCode: AttributeKey<HttpStatusCode>

routingRoot

val Application.routingRoot: RoutingNode

Gets the root of the routing block.

Functions

fun Route.accept(vararg contentTypes: ContentType, build: Route.() -> Unit): Route

Builds a route to match requests with the HttpHeaders.Accept header matching any of the specified contentTypes.

contentType

fun Route.contentType(contentType: ContentType, build: Route.() -> Unit): Route

Builds a route to match requests with the HttpHeaders.ContentType header matching the specified contentType.

createRouteFromPath

fun Route.createRouteFromPath(path: String): Route

Creates a routing entry for the specified path.

delete

fun Route.delete(body: RoutingHandler): Route

Builds a route to match DELETE requests.

fun Route.delete(path: String, body: RoutingHandler): Route

Builds a route to match DELETE requests with the specified path.

fun Route.delete(path: Regex, body: RoutingHandler): Route

Builds a route to match DELETE requests with the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

get

fun Route.get(body: RoutingHandler): Route

Builds a route to match GET requests.

fun Route.get(path: String, body: RoutingHandler): Route

Builds a route to match GET requests with the specified path.

fun Route.get(path: Regex, body: RoutingHandler): Route

Builds a route to match GET requests with the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

getAllRoutes

fun RoutingNode.getAllRoutes(): List<RoutingNode>

Return list of endpoints with handlers under this route.

head

fun Route.head(body: RoutingHandler): Route

Builds a route to match HEAD requests.

fun Route.head(path: String, body: RoutingHandler): Route

Builds a route to match HEAD requests with the specified path.

fun Route.head(path: Regex, body: RoutingHandler): Route

Builds a route to match HEAD requests with the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

header

fun Route.header(name: String, value: String, build: Route.() -> Unit): Route

Builds a route to match a header with the specified name and value.

host

fun Route.host(host: String, port: Int = 0, build: Route.() -> Unit): Route

Creates a route to match a request's host and port. There are no any host resolutions/transformations applied to a host: a request host is treated as a string.

fun Route.host(hosts: List<String>, ports: List<Int> = emptyList(), build: Route.() -> Unit): Route

fun Route.host(hostPattern: Regex, port: Int = 0, build: Route.() -> Unit): Route

Creates a route to match a request host and port. There are no any host resolutions/transformations applied to a host: a request host is treated as a string.

fun Route.host(hosts: List<String>, hostPatterns: List<Regex>, ports: List<Int> = emptyList(), build: Route.() -> Unit): Route

Creates a route to match s request host and port. There are no any host resolutions/transformations applied to a host: a request host is treated as a string.

insertPhaseAfter

fun Route.~~insertPhaseAfter~~(reference: PipelinePhase, phase: PipelinePhase)

insertPhaseBefore

fun Route.~~insertPhaseBefore~~(reference: PipelinePhase, phase: PipelinePhase)

intercept

fun Route.~~intercept~~(phase: PipelinePhase, block: suspend PipelineContext<Unit, PipelineCall>.(Unit) -> Unit)

localPort

fun Route.localPort(port: Int, build: Route.() -> Unit): Route

Creates a route to match a port on which a call was received.

method

fun Route.method(method: HttpMethod, body: Route.() -> Unit): Route

Builds a route to match the specified HTTP method.

optionalParam

fun Route.optionalParam(name: String, build: Route.() -> Unit): Route

Builds a route to capture an optional parameter with specified name, if it exists.

options

fun Route.options(body: RoutingHandler): Route

Builds a route to match OPTIONS requests.

fun Route.options(path: String, body: RoutingHandler): Route

Builds a route to match OPTIONS requests with the specified path.

fun Route.options(path: Regex, body: RoutingHandler): Route

Builds a route to match OPTIONS requests with the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

param

fun Route.param(name: String, build: Route.() -> Unit): Route

Builds a route to match a parameter with the specified name and captures its value.

fun Route.param(name: String, value: String, build: Route.() -> Unit): Route

Builds a route to match a parameter with the specified name and value.

patch

fun Route.patch(body: RoutingHandler): Route

Builds a route to match PATCH requests.

@JvmName(name = "patchTyped")

inline fun <R : Any> Route.patch(crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match PATCH requests receiving a request body as content of the R type.

fun Route.patch(path: String, body: RoutingHandler): Route

Builds a route to match PATCH requests with the specified path.

@JvmName(name = "patchTypedPath")

inline fun <R : Any> Route.patch(path: String, crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match PATCH requests with the specified path receiving a request body as content of the R type.

fun Route.patch(path: Regex, body: RoutingHandler): Route

Builds a route to match PATCH requests with the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

@JvmName(name = "patchTypedPath")

inline fun <R : Any> Route.patch(path: Regex, crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match PATCH requests with the specified regex path receiving a request body as content of the R type. Named parameters from regex can be accessed via ApplicationCall.parameters.

path

fun Route.path(format: RoutePathFormat = RoutePathFormat.Default): String

Constructs the full path of the routing node by combining the path of the parent node and the formatted path of this node's selector, using the provided format.

port

fun Route.port(vararg ports: Int, build: Route.() -> Unit): Route

Creates a route to match a request port.

post

fun Route.post(body: RoutingHandler): Route

Builds a route to match POST requests.

@JvmName(name = "postTyped")

inline fun <R : Any> Route.post(crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match POST requests receiving a request body as content of the R type.

fun Route.post(path: String, body: RoutingHandler): Route

Builds a route to match POST requests with the specified path.

@JvmName(name = "postTypedPath")

inline fun <R : Any> Route.post(path: String, crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match POST requests with the specified path receiving a request body as content of the R type.

fun Route.post(path: Regex, body: RoutingHandler): Route

Builds a route to match POST requests with the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

@JvmName(name = "postTypedPath")

inline fun <R : Any> Route.post(path: Regex, crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match POST requests with the specified regex path receiving a request body as content of the R type. Named parameters from regex can be accessed via ApplicationCall.parameters.

put

fun Route.put(body: RoutingHandler): Route

Builds a route to match PUT requests.

@JvmName(name = "putTyped")

inline fun <R : Any> Route.put(crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match PUT requests receiving a request body as content of the R type.

fun Route.put(path: String, body: RoutingHandler): Route

Builds a route to match PUT requests with the specified path.

@JvmName(name = "putTypedPath")

inline fun <R : Any> Route.put(path: String, crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match PUT requests with the specified path receiving a request body as content of the R type.

fun Route.put(path: Regex, body: RoutingHandler): Route

Builds a route to match PUT requests with the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

@JvmName(name = "putTypedPath")

inline fun <R : Any> Route.put(path: Regex, crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match PUT requests with the specified regex path receiving a request body as content of the R type. Named parameters from regex can be accessed via ApplicationCall.parameters.

query

fun Route.query(body: RoutingHandler): Route

Builds a route to match QUERY requests.

@JvmName(name = "queryTyped")

inline fun <R : Any> Route.query(crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match QUERY requests receiving a request body as content of the R type.

fun Route.query(path: String, body: RoutingHandler): Route

Builds a route to match QUERY requests with the specified path.

@JvmName(name = "queryTypedPath")

inline fun <R : Any> Route.query(path: String, crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match QUERY requests with the specified path receiving a request body as content of the R type.

fun Route.query(path: Regex, body: RoutingHandler): Route

Builds a route to match QUERY requests with the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

@JvmName(name = "queryTypedPath")

inline fun <R : Any> Route.query(path: Regex, crossinline body: suspend RoutingContext.(R) -> Unit): Route

Builds a route to match QUERY requests with the specified regex path receiving a request body as content of the R type. Named parameters from regex can be accessed via ApplicationCall.parameters.

route

fun Route.route(path: String, build: Route.() -> Unit): Route

Builds a route to match the specified path.

fun Route.route(path: Regex, build: Route.() -> Unit): Route

Builds a route to match the specified regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

fun Route.route(path: String, method: HttpMethod, build: Route.() -> Unit): Route

Builds a route to match the specified HTTP method and path.

fun Route.route(path: Regex, method: HttpMethod, build: Route.() -> Unit): Route

Builds a route to match the specified HTTP method and regex path. Named parameters from regex can be accessed via ApplicationCall.parameters.

routing

fun Application.routing(configuration: Routing.() -> Unit): RoutingRoot

Installs a RoutingRoot plugin for the this Application and runs a configuration script on it. You can learn more about routing in Ktor from Routing.