Salute Ktor!
In this post, we’re going to use Ktor to implement a web service that when called, responds with “Hello, World”. In other words, we’re going to implement the so-called “Hello, World! program” using the Ktor framework to see how easy it is to get up and running with Ktor.
A Little Bit About Ktor
Based on ktor.io, Ktor is
an asynchronous framework for creating microservices, web applications, and more.
We’ll use Ktor to implement a super simple web service, but before that let's see why someone would use Ktor.
Lightweight
Ktor allows us to transparently configure only the functionality we need. No magic involved!
Extensible
With a configurable pipeline, we can create the extensions we need and place them anywhere we want.
Multiplatform
Built from the ground up with Kotlin Multiplatform technology, you can deploy Ktor applications (almost) anywhere.
Asynchronous
Using Kotlin Coroutines, Ktor is truly asynchronous and highly scalable. We can use the power of non-blocking development, free of callback hells!
Project Setup
In order to get up and running, we’ll use the IntelliJ IDEA Community Editon with the Ktor plugin.
If you have the Ktor plugin already installed then no further action is required, but if not, open IntelliJ IDEA’s Preferences window. From the left pane select Plugins . Search for “ktor”, install it, and restart the IDE.
After installing the Ktor plugin it’s time to create a new Ktor project. To create a new project follow these steps:
From the IntelliJ IDEA’s menu select File -> New -> Project… to start the “New Project” wizard.
In the “New Project” wizard select “Ktor” from the left pane, then on the right, you can see the options that you can configure for your project. Some options available on this page are:
- Build system (Gradle, Maven, etc)
- Ktor version
- Server (Netty, Jetty, Tomcat, etc)
For the purposes of this tutorial, there is no need to touch anything on this page. So click “Next”.
On the next page fill in the GroupId , ArtifactId, and Version fields (or use the default values) and click “Next”.
On the last page enter the project name and specify a location to save the project. Then click “Finish” to have a brand new Ktor project!
Implementing the Web Service
After creating a new Ktor project, look for the file Application.kt. This file is where we implement our web service.
By default Application.kt has the following source code:
Remove the source code of Application.kt such that only an empty main function remains:
Now we can start implementing our beloved “Hello, World!” service!
The very first thing that we need to do is to start a server (aka Application Engine) to serve requests. We can do this by calling the embeddedServer function.
FunctionembeddedServer accepts several parameters and returns an instance of ApplicationEngine.
From the input parameters, just two of them are mandatory:
server: The server to use. In the example below, we’ll use Netty.requestHandler: a lambda which is called whenever a request is received. BecauserequestHandleris the last parameter ofembeddedServerso we’re going to use Kotlin’s trailing-lambda syntax.
After calling the embeddedServer function we call the start method on the returned ApplicationEngine instance to keep the server running.
Note: If we take a look at the source code of embeddedServer function we see that the actual name of parameters server and requestHandler are factory and module respectively. Here We’ve used server and requestHandler because these names make more sense!
Now that our server is up and running it’s time to handle routes.
In order to handle routes, we call the routing function. This function has a single parameter named configuration which is a lambda. Inside this lambda is where we handle different routes.
In the above example, we’ve called the get function to handle GET requests to the /hello route. The get function accepts two parameters:
path: the path (or route) to handle,body: a lambda that processes the request.
Now it’s time to return a response as the result of making a GET request to /hello.
Inside the lambda body of the parameter body of method get , we have access to an instance of ApplicationCall named call. We can use call to return a response like below.
Calling respondText returns the given text (with a content type of ContentType.Text.Plain) as the result of making a GET request to /hello.
That’s it. We are done implementing our “Hello, World! program” using Ktor!
Running the Web Service
After implementing our “Hello, World!” service it’s time to run it and see it in action.
To run the application just click the little green “play” button next to the beginning of the main function.
Now open a web browser and enter http://0.0.0.0/hello into its address bar to see the result.
Voila! We have implemented our very first web service using Ktor!
As you saw getting up and running with Ktor is super easy, but Ktor has a lot more to offer. To read more about Ktor take a look at its official documentation.
If you find this post useful then clapping is appreciated (1, 2, or maybe 50 claps!)
P.S: the complete source code of this tutorial is available here.
