As a web application toolkit, Ktor provides the essential components for building the application, like routing, authentication, and utilities for working with various protocols, including HTTP and WebSockets. For other use cases, such as working with databases, developers are free to pick any libraries that suit their needs.<\/p>\n\n\n\n
In this article, we provide a quick overview of Ktor\u2019s features to help you get started with this tool.<\/p>\n\n\n\n
The \u201cHello, World!\u201d app<\/h2>\n\n\n\n
Starting a new project with Ktor is easy. You can use the project generator available at start.ktor.io<\/a> or the New Project<\/em> wizard in IntelliJ IDEA<\/a>.<\/p>\n\n\n\n The equivalent of a Hello World<\/strong> application with Ktor would be:<\/p>\n\n\n\n To begin, we’re instantiating a server that utilizes Netty<\/a> as its underlying engine and operates on port 8080.<\/p>\n\n\n\n Next, we define a specific route to handle incoming requests. In this instance, we’re instructing the server to respond with the plain text message Last, we initiate the server and instruct it to wait, thereby preventing our application from terminating immediately.<\/p>\n\n\n\n That\u2019s as simple as it gets when it comes to Ktor. To implement additional functionality, we would need to define additional HTTP verbs and their corresponding URLs within the Or we can regroup the endpoints by declaring a Grouping endpoints into routes is useful for enabling Ktor plugins, such as content negotiation, within the scope of each route.<\/p>\n\n\n\n To demonstrate how Ktor leverages Kotlin\u2019s features, let\u2019s extract the individual endpoints into extension functions<\/a> for the Route type:<\/p>\n\n\n\n The new functions, The purpose of content negotiation is to handle the conversion between different data formats when communicating between the client and the server. In Ktor, content negotiation also enables automatic serialization and deserialization of data formats such as JSON, XML, or other types, based on the The following example demonstrates the use of content negotiation<\/a> with JSON serialization for the Message data class:<\/p>\n\n\n\n First, even if the dependency that implements the corresponding feature is present in the classpath of the project, in Ktor, we have to explicitly enable this functionality. This is done using the This approach avoids the implicit behavior that could be imposed by the accidental presence of a dependency artifact in the classpath.<\/p>\n\n\n\n As soon as the content negotiation is configured, the endpoints are ready to interact with the intended format. In our example, the We\u2019ve already mentioned the plugins in the previous part about content negotiation. Ktor provides a number of plugins out of the box, as well as a simple API to implement your own plugins. However, Ktor doesn\u2019t prevent you from using any of your favorite libraries without a plugin. A plugin is just a convenience that enables common configuration and a coherent code style.<\/p>\n\n\n\n The plugins can be enabled for the application instance or for the selected routes. The full list of plugins can be found in the project generator<\/a> or in the GitHub repository for the plugins registry<\/a>, where plugin developers can contribute by registering their plugins.<\/p>\n\n\n\n Ktor provides a powerful interception mechanism that allows you to add custom behavior to your application. This offers flexibility similar to aspect-oriented programming, but in a more Kotlin-idiomatic way.<\/p>\n\n\n\n To create an interceptor, we only need to create an instance of an application plugin using the In our example, the The Ktor project started as a testbed for Kotlin coroutines<\/a>. This is why it provides native support for asynchronous programming. This allows for more intuitive, sequential-looking code that’s actually non-blocking.<\/p>\n\n\n\n In this example, You will notice that the editor shows the special icons in the gutter, indicating that there is a suspending function invocation on the corresponding line:<\/p>\n\n\n\n On lines 17, 19, and 21, the icons in the gutter indicate invocations of the asynchronous functions.<\/em><\/p>\n\n\n\n When working with Ktor, you will notice that even though the application code looks sequential, there are a lot of functions highlighted in the gutter with these icons. This is a hint for you that in those places, the execution is actually asynchronous.<\/p>\n\n\n\n Thanks to coroutines, Ktor makes it easy to add real-time, bidirectional communication to your application using WebSockets<\/a>. Here is an example of a very simple echo server with WebSockets:<\/p>\n\n\n\n The server sets up a WebSocket endpoint at Ktor was designed with testability in mind. It provides a test engine that allows you to test your application without starting a real server:<\/p>\n\n\n\n The provided test code demonstrates how Ktor allows you to write tests for your application using its TestEngine<\/a>. The test simulates an HTTP request to the Ktor server without needing to start an actual server, which is both faster and easier to manage during development. This makes writing comprehensive tests for your Ktor applications a breeze, including full integration tests.<\/p>\n\n\n\n Ktor provides a flexible authentication system that supports various authentication methods. Below is an example of basic authentication:<\/p>\n\n\n\n The example demonstrates how to implement basic authentication in Ktor. When a client, such as a browser, requests the root path (‘\/’) without providing an Upon receiving this response, the client typically displays a login dialog for the user to enter their credentials. The client then makes a new request, this time including an Once the server receives a properly authenticated request, it validates the credentials and allows access to the root endpoint (‘\/’). In this example, the endpoint responds with a personalized message: “Hello, username”.<\/p>\n\n\n\n Ktor also supports other authentication methods, including form-based<\/a>, JWT<\/a>, and OAuth<\/a>.<\/p>\n\n\n\n Serving static content<\/a> is an integral part of the routing functionality. Thus, an extra plugin is not required and the functionality is enabled by default. To configure the resource mapping, we can use Ktor\u2019s API functions, such as The root path (\u2018\/\u2019) is mapped to the `static` folder in the project.<\/em><\/p>\n\n\n\n By using the status pages<\/a> plugin, we can configure how the application responds to exceptions and status codes.<\/p>\n\n\n\n This setup provides custom responses for unauthorized access and any other unhandled exception that might occur during the execution. For the 404 status code, the request is redirected to a static resource, assuming the static resources are configured accordingly.<\/p>\n\n\n\n Ktor offers a fresh, Kotlin-first approach to building server-side applications. Its coroutine-based architecture, modular design, and type-safe API provide a powerful toolkit for modern application development. Ktor’s flexibility and performance make it an excellent choice for microservices, API backends, and other modern application architectures.<\/p>\n\n\n\n For Java developers looking to leverage Kotlin’s strengths in their server-side applications, Ktor provides a compelling toolkit that’s worth exploring. Its learning curve is relatively gentle for those already familiar with Kotlin, and the benefits in terms of code conciseness and performance can be significant.<\/p>\n\n\n\n This article provided a brief overview of Ktor\u2019s features. For more examples, we recommend the samples repository on GitHub<\/a> where we showcase various features provided out of the box.<\/p>\n\n\n\nfun main() {\n embeddedServer(Netty, port = 8080, host = \"0.0.0.0\") {\n routing {\n get(\"\/hello\") {\n call.respondText(\"Hello, World!\")\n }\n }\n }.start(wait = true)\n}<\/pre>\n\n\n\nHello, World!<\/code> when a request is made to the \/hello<\/code> path.<\/p>\n\n\n\nrouting<\/code> function. For instance, if we\u2019d like to respond to POST, we\u2019d simply add another function:<\/p>\n\n\n\n routing {\n get(\"\/hello\") {\n call.respondText(\"Hello, World!\")\n }\n post(\"\/hello\") {\n \/\/ \u2026\n }\n }<\/pre>\n\n\n\nroute<\/code> and specify the HTTP verbs for that route as follows:<\/p>\n\n\n\n routing {\n route(\"\/hello\") {\n get {\n call.respondText(\"Hello, World!\")\n }\n post {\n \/\/ \u2026\n }\n }\n }<\/pre>\n\n\n\n routing {\n route(\"\/hello\") {\n getEndpoint()\n postEndpoint()\n }\n }\n\n private fun Route.getEndpoint() {\n get { \u2026 }\n }\n\n private fun Route.postEndpoint() {\n post { \u2026 }\n }<\/pre>\n\n\n\ngetEndpoint<\/code> and postEndpoint<\/code>, are defined as extensions of Ktor\u2019s Route class, meaning they can only be used inside the route { \u2026 }<\/code> DSL block. Ktor relies heavily on type-safe builders<\/a> for its DSLs, giving the code a more declarative style.<\/p>\n\n\n\nContent negotiation<\/h2>\n\n\n\n
Content-Type<\/code> headers in HTTP requests and responses.<\/p>\n\n\n\n@Serializable\ndata class Message(val id: String, val message: String)\n\nembeddedServer(Netty, port = 8080, host = \"0.0.0.0\") {\n install(ContentNegotiation) {\n json()\n }\n routing {\n route(\"\/hello\") {\n get {\n call.respond(Message(\"123ABC\", \"Hello, World!\"))\n }\n post {\n val message = call.receive<Message>()\n \/\/ do something with the message\n }\n }\n }\n\n}.start(wait = true)<\/pre>\n\n\n\ninstall<\/code> function, with the feature name following a configuration block.<\/p>\n\n\n\n install(ContentNegotiation) {\n json()\n }<\/pre>\n\n\n\nMessage<\/code> data class will be serialized to JSON in the GET endpoint on the call.respond(...)<\/code> invocation, and deserialized in the POST endpoint on call.receive<Message>()<\/code> invocation.<\/p>\n\n\n\nPlugins<\/h2>\n\n\n\n
install(ContentNegotiation) {\n json()\n}\ninstall(WebSockets) {\n pingPeriod = Duration.ofSeconds(15)\n timeout = Duration.ofSeconds(15)\n maxFrameSize = Long.MAX_VALUE\n masking = false\n}\ninstall(Compression) {\n gzip {\n minimumSize(1024)\n }\n}\ninstall(CORS) {\n allowMethod(HttpMethod.Put)\n allowHeader(\"MyCustomHeader\")\n}<\/pre>\n\n\n\nExtensibility through interceptors<\/h2>\n\n\n\n
createApplicationPlugin<\/code> function. In the plugin, we can implement custom logic for handling requests and responses using a set of handlers<\/a> that provide access to different stages of a call.<\/p>\n\n\n\nval UserAgentValidation = createApplicationPlugin(\"UserAgent\") {\n onCall { call ->\n val userAgent = call.request.headers[\"User-Agent\"]\n ?: throw UnsupportedUserAgentException()\n if (userAgent.isNotBrowser())\n call.respond(HttpStatusCode.Forbidden)\n }\n}\n\ninstall(UserAgentValidation)<\/pre>\n\n\n\nonCall<\/code> function implements the logic of checking the user agent header and rejecting any clients that aren\u2019t web browsers. Keep in mind, we still need to use the install<\/code> function to activate the plugin.<\/p>\n\n\n\nKotlin Coroutines<\/h2>\n\n\n\n
import io.ktor.server.application.*\nimport io.ktor.server.response.*\nimport io.ktor.server.routing.*\n\nfun Application.module() {\n routing {\n get(\"\/api\/users\") {\n selectAllUsers().let {\n call.respond(it)\n }\n }\n }\n}\n\nsuspend fun selectAllUsers(): List<User> =\n newSuspendedTransaction(Dispatchers.IO) {\n UserTable.selectAll()\n .orderBy(UserTable.id, SortOrder.ASC)\n .map { row: ResultRow ->\n User(\n userId = row[UserTable.id],\n name = row[UserTable.name],\n \/\/ map more columns\n )\n }\n }\n\nobject UserTable : Table(\"users\") {\n val id = long(\"id\").autoIncrement()\n\n val name = varchar(\"name\", 50).uniqueIndex()\n val email = text(\"email\").uniqueIndex()\n val link = text(\"link\").nullable()\n val userType = enumeration<UserType>(\"user_type\")\n\n override val primaryKey: Table.PrimaryKey = PrimaryKey(id)\n}<\/pre>\n\n\n\nselectAllUsers<\/code> is marked with the suspend<\/code> keyword, meaning that it can pause its execution without blocking the thread. In this example, we use the Exposed<\/a> library for accessing the database and then mapping the results of the query to a User<\/code> object.<\/p>\n\n\n\n![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/09\/ktor-async-invocations-1.png\")
<\/figure>\n\n\n\nWebSockets<\/h2>\n\n\n\n
fun main() {\n embeddedServer(Netty, port = 8080) {\n install(WebSockets)\n routing {\n webSocket(\"\/chat\") {\n send(\"You are connected!\")\n for (frame in incoming) {\n frame as? Frame.Text ?: continue\n val receivedText = frame.readText()\n send(\"You said: $receivedText\")\n }\n }\n }\n }.start(wait = true)\n}<\/pre>\n\n\n\n\/chat<\/code> that echoes back messages prefixed with “You said: “.<\/p>\n\n\n\nTestability<\/h2>\n\n\n\n
import io.ktor.client.request.*\nimport io.ktor.client.statement.*\nimport io.ktor.http.*\nimport io.ktor.server.testing.*\nimport kotlin.test.*\n\nclass ApplicationTest {\n @Test\n fun testRoot() = testApplication {\n application { \n module()\n }\n client.get(\"\/\").apply {\n assertEquals(HttpStatusCode.OK, status)\n assertEquals(\"Hello, World!\", bodyAsText())\n }\n }\n}<\/pre>\n\n\n\nAuthentication<\/h2>\n\n\n\n
embeddedServer(Netty, port = 8080, host = \"0.0.0.0\") {\n install(Authentication) {\n basic(\"auth-basic\") {\n realm = \"Access to the '\/' path\"\n validate { credentials ->\n if (credentials.name == \"username\" \n && credentials.password == \"password\") {\n UserIdPrincipal(credentials.name)\n } else {\n null\n }\n }\n }\n }\n\n routing {\n authenticate(\"auth-basic\") {\n get(\"\/\") {\n call.respondText(\"Hello,\n ${call.principal<UserIdPrincipal>()?.name}!\")\n }\n }\n }\n\n}.start(wait = true)<\/pre>\n\n\n\nAuthorization<\/code> header, the server responds with a 401<\/code> (Unauthorized) status code. It also includes a WWW-Authenticate<\/code> response header, signaling that the route is protected by basic authentication.<\/p>\n\n\n\nAuthorization<\/code> header containing the Base64-encoded username and password pair.<\/p>\n\n\n\nServing static content<\/h2>\n\n\n\n
staticResources<\/code> in the example below:<\/p>\n\n\n\n![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/09\/ktor-static-resources.png\")
<\/figure>\n\n\n\nStatus Pages<\/h2>\n\n\n\n
install(StatusPages) {\n exception<AuthorizationException> { call, cause ->\n call.respond(HttpStatusCode.Forbidden)\n }\n exception<Throwable> { call, cause ->\n call.respondText(text = \"500: ${cause.localizedMessage}\",\n status = HttpStatusCode.InternalServerError)\n }\n status(HttpStatusCode.NotFound) { call, _ ->\n call.respondRedirect(\"\/404.html\", permanent = true) \/\/ 301\n }\n}<\/pre>\n\n\n\nConclusion<\/h2>\n\n\n\n