Eventually, we will get the below user table:

But before we start, just a short disclaimer: although the main focus for this tutorial is the htmx / Kotlin / Ktor combination, I decided to bring Tailwind CSS to the project with the help of Material Tailwind components. This way, I wanted to showcase the code that is closer to real-life scenarios. Not a next, plain HTML example.

So, although I tried my best, please keep in mind that the HTML part may need some more love when adapting 🫡

Note: if you enjoy this content and would like to learn Ktor step-by-step, then check out my Ktor Server Pro course.

Video Tutorial

If you prefer video content, then check out my video:

What is htmx?

If you are here, then there is a high chance you’ve been looking for a Kotlin & htmx combination, so you already know what it is.

Nevertheless, so we are all on on the same page:

It is a library that allows you to access modern browser features directly from HTML, rather than using javascript.

And we could add plenty of other things here, like the fact that it is small, dependency-free, and allows us to use AJAX, CSS Transitions, WebSockets, and so on.

But, IMO, the most important thing from the practical standpoint is that we can use attributes in HTML, and the library will do the “magic” for us:

<td>
  <button hx-delete="/users/7a9079f0-c5a2-45d0-b4ae-e304b6908787" hx-swap="outerHTML" hx-target="closest tr">
... the rest
   

The above following snippet means that when we click the button:

• the DELETE /users/7a9079f0-c5a2-45d0-b4ae-e304b6908787 request is made
• the closest tr element is replaced with the HTML response we receive

And I believe this is all we need to know for now.

Again, a short note from my end: the htmx documentation is a great resource, and I will refer a lot to it throughout this course to not reinvent the wheel. But at the same time, I want to deliver you a fully-contained article so that you don’t need to jump between pages 😉

Generate Ktor Project

As the first step, let’s quickly generate a new Ktor project using https://start.ktor.io/:

As we can see, the only plugin we need to select is the Kotlin HTML DSL (this way, the Routing plugin is added, too).

Regarding the config, we are going to use Ktor 3.1.1 with Netty, YAML config, and without a version catalog. But, of course, feel free to adjust it here according to your needs.

With that done, let’s download the project and import it to our IDE.

Create User Repository

Following, let’s add the repository package and introduce a simple, in-memory user repository:

data class User(
    val id: String = UUID.randomUUID().toString(),
    val firstName: String,
    val lastName: String,
    val enabled: Boolean,
    val createdAt: LocalDateTime = LocalDateTime.now(),
)
class UserRepository {
    private val users = mutableListOf(
        User(firstName = "Jane", lastName = "Doe", enabled = true),
        User(firstName = "John", lastName = "Smith", enabled = true),
        User(firstName = "Alice", lastName = "Johnson", enabled = false),
        User(firstName = "Bob", lastName = "Williams", enabled = true),
    )
    fun create(firstName: String, lastName: String, enabled: Boolean): User =
        User(firstName = firstName, lastName = lastName, enabled = enabled)
            .also(users::add)
    fun findAll(): List<User> = users
    fun delete(id: String): Boolean = users.removeIf { it.id == id }
}

As we can see, nothing spectacular. Just 3 functions responsible for creating, searching, and deleting users.

Return HTML Response in Ktor

Following, let’s add the routing package and Routing.kt:

fun Application.configureRouting(userRepository: UserRepository) {
    routing {
        get("/") {
            call.respondHtml {
                renderIndex(userRepository)
            }
        }
    }
}

And update the main Application.kt to incorporate those changes:

fun Application.module() {
    val userRepository = UserRepository()
    configureRouting(userRepository)
}

In a moment, we will add the renderIndex function, but for now, let’s focus on the above.

Long story short, the above code instructs the Ktor server to respond with the HTML response whenever it reaches the root path. By default, the localhost:8080.

Generate HTML page with Kotlin DSL

With that done, we have everything we need to start returning HTML responses. So in this section, we will prepare the baseline for htmx.

Note: if you feel that continuous server restarting is painful, please check out how to enable auto-reload in Ktor?

Render Homepage

As the first step, let’s add the html package and the renderIndex function in Index.kt:

import com.codersee.repository.UserRepository
import kotlinx.html.*
fun HTML.renderIndex(userRepository: UserRepository) {
    body {
        div {
            insertHeader()
        }
    }
}
private fun FlowContent.insertHeader() {
    h5 {
        +"Users list"
    }
}

At this point, such a structure is overengineering. Nevertheless, our codebase is about to grow quickly in this tutorial, so we rely on Kotlin extension functions from the very beginning.

And as we can see, we use the HTML that represents the root element of an HTML document. Inside it, we can define the structure in a type-safe manner, thanks to the Kotlin DSL feature. For the inner tags, we can use the FlowContent that is the marker interface for plenty of classes representing HTML tags, like div, headers, or the body.

And before we rerun the application, we must add the necessary import in Routing.kt:

import com.codersee.repository.html.renderIndex

With that done, let’s rerun the application and verify that everything is working.

Insert HTML Form

Following, let’s use the HTML DSL to define the user form.

As the first step, let’s add the Form.kt to inside the html package:

import kotlinx.html.*
fun FlowContent.insertUserForm() {
    div {
        form {
            div {
                div {
                    label {
                        htmlFor = "first-name"
                        +"First Name"
                    }
                    input {
                        type = InputType.text
                        name = "first-name"
                        id = "first-name"
                        placeholder = "First Name"
                    }
                }
                div {
                    label {
                        htmlFor = "last-name"
                        +"Last Name"
                    }
                    input {
                        type = InputType.text
                        name = "last-name"
                        id = "last-name"
                        placeholder = "Last Name"
                    }
                }
                div {
                    label {
                        +"Account enabled"
                    }
                    div {
                        div {
                            input {
                                type = InputType.radio
                                name = "enabled-radio"
                                id = "radio-button-1"
                                value = "true"
                            }
                            label {
                                htmlFor = "radio-button-1"
                                +"Yes"
                            }
                        }
                        div {
                            input {
                                type = InputType.radio
                                name = "enabled-radio"
                                id = "radio-button-2"
                                value = "false"
                                checked = true
                            }
                            label {
                                htmlFor = "radio-button-2"
                                +"No"
                            }
                        }
                    }
                }
                div {
                    button {
                        +"Add user"
                    }
                }
            }
        }
    }
}

As we can see, the Kotlin DSL allows us to define everything in a neat, structured manner. And although I had a chance to use it in various places, with HTML, it feels so…natural. We write the code pretty similar to HTML.

Of course, before heading to the next part, let’s make use of our function:

fun HTML.renderIndex(userRepository: UserRepository) {
    body {
        div {
            insertHeader()
            insertUserForm()
        }
    }
}

We can clearly see that the extraction was a good idea 😉

Create User Table

As the next step, let’s add the UserTable.kt:

import com.codersee.repository.User
import kotlinx.html.*
import java.time.format.DateTimeFormatter
fun FlowContent.insertUserTable(users: List<User>) {
    div {
        table {
            thead {
                tr {
                    th {
                        +"User"
                    }
                    th {
                        +"Status"
                    }
                    th {
                        +"Created At"
                    }
                    th {}
                }
            }
            tbody {
                id = "users-table"
                users.forEach { user ->
                    tr {
                        insertUserRowCells(user)
                    }
                }
            }
        }
    }
}
fun TR.insertUserRowCells(user: User) {
    td {
        div {
            p {
                +"${user.firstName} ${user.lastName}"
            }
        }
    }
    td {
        div {
            div {
                val enabledLabel = if (user.enabled) "Enabled" else "Disabled"
                val labelColor = if (user.enabled) "green" else "red"
                span { +enabledLabel }
            }
        }
    }
    td {
        p {
            +user.createdAt.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
        }
    }
    td {
        button {
            + "Delete"
        }
    }
}

As we can see this time, the Kotlin HTML DSL allows us to easily generate dynamic HTML tags. We use the passed user list to create a row for every user we “persisted”. We even make the decision about the label and future color based on the list.

Again, let’s get back to Routing.kt and invoke our function:

fun HTML.renderIndex(userRepository: UserRepository) {
    body {
        div {
            insertHeader()
            insertUserForm()
            insertUserTable(userRepository.findAll())
        }
    }
}

And although I am pretty sure it won’t become the eighth wonder of the World, our application starts looking similar to what we want to achieve:

htmx and Kotlin

With all of that done, we have everything prepared to start actually working with htmx and Kotlin.

Again, you will see a lot of references taken from the docs (which I encourage you to visit after this tutorial).

Import

As the first step, let’s import htmx.

Again, it is nothing else than the JavaScript library, so the only thing we need is to add it inside the script block of our HTML.

And the easiest way is to simply fetch it from their CDN and put it inside the Kotlin script DSL block:

fun HTML.renderIndex(userRepository: UserRepository) {
    head {
        script {
            src = "https://unpkg.com/htmx.org@2.0.4"
        }
    }
    body {
        div {
            insertHeader()
            insertUserForm()
            insertUserTable(userRepository.findAll())
        }
    }
}

AJAX Requests – Create User

As we saw in the very beginning, htmx allows us to define requests with attributes.

To be more specific, we can use the following attributes:

• hx-get
• hx-post
• hx-put
• hx-patch
• hx-delete

And, long story short, when the element is triggered, an AJAX request is made to the specified URL.

So, let’s update our form then:

fun FlowContent.insertUserForm() {
    div {
        form {
            attributes["hx-post"] = "/users"
... the rest

This way, our html now contains:

<form hx-post="/users">

And when we hit the Add user button, we can see that the request is triggered (but, it results in 404 response given we have no handler).

So, let’s add the endpoint responsible for user creation:

fun Application.configureRouting(userRepository: UserRepository) {
    routing {
        get("/") {
            call.respondHtml {
                renderIndex(userRepository)
            }
        }
        route("/users") {
            post {
                val formParams = call.receiveParameters()
                val firstName = formParams["first-name"]!!
                val lastName = formParams["last-name"]!!
                val enabled = formParams["enabled-radio"]!!.toBoolean()
                val createdItem = userRepository.create(firstName, lastName, enabled)
                val todoItemHtml = createHTML().tr { insertUserRowCells(createdItem) }
                call.respondText(
                    todoItemHtml,
                    contentType = ContentType.Text.Html,
                )
            }
        }
    }
}

At this point, it should not be a surprise, but we can see that in Ktor, we can do that quite easily.

Our code snippet will read the form parameters sent from the browser, “create” a new user, and return a 200 OK response with:

<tr>
  <td>
    <div>
      <p>Admiral Jahas</p>
    </div>
  </td>
  <td>
    <div>
      <div><span>Disabled</span></div>
    </div>
  </td>
  <td>
    <p>2025-03-29 08:16:40</p>
  </td>
  <td><button>Delete</button></td>
</tr>

The important thing to mention here is that respondHtml requires us to respond with whole body! So, to bypass that, we use the respondText function and set the content type as HTML.

However, when we open up the browser, we can see this:

And I am pretty sure that is not what we wanted 😀

htmx Target

Lesson one: if we want to instruct htmx to load the response into a different element than the one that made the request, we must use the hx-target attribute that takes the CSS selector, or:

• this keyword- to refer to the element with hx-target attribute
• closest, next, previous <CSS selector> (like closest div)- to target the closest ancestor element or itself
• find <CSS selector – to target the first child descendant element that matches the given CSS selector

As a proof, let’s take a look at what happened previously:

As we can see, the table row was inserted inside the form. And that does not make sense, at all.

So, to fix that, let’s target the table tbody instead:

fun FlowContent.insertUserForm() {
    div {
        form {
            attributes["hx-post"] = "/users"
            attributes["hx-target"] = "#users-table"

As a result, all the other rows are deleted, but it seems to be closer to what we want:

Swapping in htmx

Next lesson: by default, htmx replaces the innerHTML of the target element.

So, in our case, the user was added successfully. We can even refresh the page and see that the array contains all created users. However, we have not defined the hx-swap so the tbody inner HTML was deleted, and our returned one was inserted instead.

So, we must add the hx-swap with one of the following values:

• innerHTML– puts the content inside the target element
• outerHTML– replaces the entire target element with the returned content
• afterbegin– prepends the content before the first child inside the target
• beforebegin– prepends the content before the target in the target’s parent element
• beforeend– appends the content after the last child inside the target
• afterend– appends the content after the target in the target’s parent element
• delete– deletes the target element regardless of the response
• none– does not append content from response (Out of Band Swaps and Response Headers will still be processed)

And in our case, the beforeend is the one we should pick to append the created user at the end of the list:

fun FlowContent.insertUserForm() {
    div {
        form {
            attributes["hx-post"] = "/users"
            attributes["hx-target"] = "#users-table"
            attributes["hx-swap"] = "beforeend"

When we restart the app, everything works fine! 🙂

Dynamic htmx Tags in Kotlin

At this point, we know how to display and add new users with htmx. So, let’s learn how to delete them.

As the first step, let’s prepare a Ktor handler inside the route("/users") for the DELETE request:

delete("/{id}") {
    val id = call.parameters["id"]!!
    userRepository.delete(id)
    call.respond(HttpStatusCode.OK)
}

With that code, whenever a DELETE /users/{some-id} is made, we remove the user from our list and return 200 OK.

Important lesson here: for simplicity, we return 200 OK (and not 204 No Content), because by default, htmx ignores successful responses other than 200.

Following, let’s update our button:

td {
        button {
            attributes["hx-delete"] = "/users/${user.id}"
            attributes["hx-swap"] = "outerHTML"
            attributes["hx-target"] = "closest tr"

So, firstly, whenever we generate our button, we use Kotlin string interpolation to put the user identifier in the hx-delete attribute value. A neat and easy way to achieve that with Kotlin.

When it comes to swapping, we want to find the closest tr parent and swap the entire element with the response. And as the response contains nothing, it will be simply removed😉

After we rerun the application, we will see everything working perfectly fine!

Error Handling with Ktor and htmx

Following, let’s learn how we can handle any Ktor error response in htmx.

For that purpose, let’s update the POST handler in Ktor:

post {
    val formParams = call.receiveParameters()
    val firstName = formParams["first-name"]!!
    val lastName = formParams["last-name"]!!
    val enabled = formParams["enabled-radio"]!!.toBoolean()
    if (firstName.isBlank() || lastName.isBlank())
        return@post call.respond(HttpStatusCode.BadRequest)
... the rest of the code

With that validation, whenever first-name or last-name form parameter is blank, the API client receives 400 Bad Request.

After we restart the server and try to make a request without passing first or last name, we see that nothing is happening. No pop-ups, alerts, nothing. The only indication that the request is actually made is thenetwork tab of our browser.

Well, unfortunately (or fortunately?), htmx does not provide any handling out-of-the-box.

But, it throws two events:

• htmx:responseError– in the event of an error response from the server, like 400 Bad Request
• htmx:sendError– in case of connection error

So, let’s add a tiny bit of JS in Kotlin, then:

private fun BODY.insertErrorHandlingScripts() {
    script {
        +"""
            document.body.addEventListener('htmx:responseError', function(evt) {
              alert('An error occurred! HTTP status:' + evt.detail.xhr.status);
            });
            
            document.body.addEventListener('htmx:sendError', function(evt) {
              alert('Server unavailable!');
            });
        """.trimIndent()
    }
}

And let’s add this script at the end of the body when rendering the homepage:

fun HTML.renderIndex(userRepository: UserRepository) {
    head {
        script {
            src = "https://unpkg.com/htmx.org@2.0.4"
        }
    }
    body {
        div {
            insertHeader()
            insertUserForm()
            insertUserTable(userRepository.findAll())
        }
        insertErrorHandlingScripts()
    }
}

Excellent! From now on, whenever the API client receives an error response, the alert is displayed. Moreover, if we turn off our server, we will see the error response, too.

And basically, that is all for the htmx part with Kotlin. From now on, we are going to work on the styling of our application😉

Returning Images in Ktor

Before we head to the Tailwind CSS part, let’s learn one more thing in Ktor: static responses handling.

So, let’s put the below image in the resources -> img directory:

And let’s add this image as a placeholder to each row in our table:

fun TR.insertUserRowCells(user: User) {
    td {
        div {
            img {
                src = "/img/placeholder.png"
            }

When we rerun the application, we can see that it does not work.

Well, to fix that, we must instruct Ktor to serve our resources as static content:

fun Application.configureRouting(userRepository: UserRepository) {
    routing {
        staticResources("/img", "img")

This time, when we restart the application, we see that placeholders are working fine.

And we will style them in a moment 😉

Styling With Tailwind CSS

At this point, we have a fully working Kotlin and htmx integration.

So, if we already did something else than the JSON response, let’s make it nice😄

Import Tailwind

Just like with htmx, let’s use the CDN to import Tailwind to the project:

fun HTML.renderIndex(userRepository: UserRepository) {
    head {
        script {
            src = "https://unpkg.com/htmx.org@2.0.4"
        }
        script {
            src = "https://unpkg.com/@tailwindcss/browser@4"
        }
    }

Update Index

Then, let’s navigate to the Index.kt and add adjustments:

fun HTML.renderIndex(userRepository: UserRepository) {
    head {
        script {
            src = "https://unpkg.com/htmx.org@2.0.4"
        }
        script {
            src = "https://unpkg.com/@tailwindcss/browser@4"
        }
    }
    body {
        div {
            classes = setOf("m-auto max-w-5xl w-full overflow-hidden")
            insertHeader()
            insertUserForm()
            insertUserTable(userRepository.findAll())
        }
        insertErrorHandlingScripts()
    }
}
private fun FlowContent.insertHeader() {
    h5 {
        classes =
            setOf("py-8 block font-sans text-xl antialiased font-semibold leading-snug tracking-normal text-blue-gray-900")
        +"Users list"
    }
}
private fun BODY.insertErrorHandlingScripts() {
    script {
        +"""
            document.body.addEventListener('htmx:responseError', function(evt) {
              alert('An error occurred! HTTP status:' + evt.detail.xhr.status);
            });
            
            document.body.addEventListener('htmx:sendError', function(evt) {
              alert('Server unavailable!');
            });
        """.trimIndent()
    }
}

As we can see, we can use the classes in Kotlin HTML DSL to prive classes names as a Set of String values:

classes = setOf(“m-auto max-w-5xl w-full overflow-hidden”)

In my case, I prefer simply copy-pasting those values instead of separating them with colons.

Refactor Form

Then, let’s update the Form.kt:

fun FlowContent.insertUserForm() {
    div {
        classes = setOf("mx-auto w-full")
        form {
            attributes["hx-post"] = "/users"
            attributes["hx-target"] = "#users-table"
            attributes["hx-swap"] = "beforeend"
            div {
                classes = setOf("-mx-3 flex flex-wrap")
                div {
                    classes = setOf("w-full px-3 sm:w-1/4")
                    label {
                        classes = setOf("mb-3 block text-base font-medium text-[#07074D]")
                        htmlFor = "first-name"
                        +"First Name"
                    }
                    input {
                        classes =
                            setOf("w-full rounded-md border border-[#e0e0e0] bg-white py-3 px-6 text-base font-medium text-[#6B7280] outline-none focus:border-[#6A64F1] focus:shadow-md")
                        type = InputType.text
                        name = "first-name"
                        id = "first-name"
                        placeholder = "First Name"
                    }
                }
                div {
                    classes = setOf("w-full px-3 sm:w-1/4")
                    label {
                        classes = setOf("mb-3 block text-base font-medium text-[#07074D]")
                        htmlFor = "last-name"
                        +"Last Name"
                    }
                    input {
                        classes =
                            setOf("w-full rounded-md border border-[#e0e0e0] bg-white py-3 px-6 text-base font-medium text-[#6B7280] outline-none focus:border-[#6A64F1] focus:shadow-md")
                        type = InputType.text
                        name = "last-name"
                        id = "last-name"
                        placeholder = "Last Name"
                    }
                }
                div {
                    classes = setOf("w-full px-3 sm:w-1/4")
                    label {
                        classes = setOf("mb-3 block text-base font-medium text-[#07074D]")
                        +"Account enabled"
                    }
                    div {
                        classes = setOf("flex items-center space-x-6 pt-3")
                        div {
                            classes = setOf("flex items-center")
                            input {
                                classes = setOf("h-5 w-5")
                                type = InputType.radio
                                name = "enabled-radio"
                                id = "radio-button-1"
                                value = "true"
                            }
                            label {
                                classes = setOf("pl-3 text-base font-medium text-[#07074D]")
                                htmlFor = "radio-button-1"
                                +"Yes"
                            }
                        }
                        div {
                            classes = setOf("flex items-center")
                            input {
                                classes = setOf("h-5 w-5")
                                type = InputType.radio
                                name = "enabled-radio"
                                id = "radio-button-2"
                                value = "false"
                                checked = true
                            }
                            label {
                                classes = setOf("pl-3 text-base font-medium text-[#07074D]")
                                htmlFor = "radio-button-2"
                                +"No"
                            }
                        }
                    }
                }
                div {
                    classes = setOf("w-full px-3 sm:w-1/4 pt-8")
                    button {
                        classes =
                            setOf("cursor-pointer rounded-md bg-slate-800 py-3 px-8 text-center text-base font-semibold text-white outline-none")
                        +"Add user"
                    }
                }
            }
        }
    }
}

Similarly, we don’t change anything in here apart from adding a bunch of classes. A whooooole bunch of classes 🙂

Modify User Table

As the last step, let’ apply changes to our user table:

fun FlowContent.insertUserTable(users: List<User>) {
    div {
        classes = setOf("px-0 overflow-scroll")
        table {
            classes = setOf("w-full mt-4 text-left table-auto min-w-max")
            thead {
                tr {
                    th {
                        classes = setOf("p-4 border-y border-blue-gray-100 bg-blue-gray-50/50")
                        +"User"
                    }
                    th {
                        classes = setOf("p-4 border-y border-blue-gray-100 bg-blue-gray-50/50")
                        +"Status"
                    }
                    th {
                        classes = setOf("p-4 border-y border-blue-gray-100 bg-blue-gray-50/50")
                        +"Created At"
                    }
                    th {
                        classes = setOf("p-4 border-y border-blue-gray-100 bg-blue-gray-50/50")
                    }
                }
            }
            tbody {
                id = "users-table"
                users.forEach { user ->
                    tr {
                        insertUserRowCells(user)
                    }
                }
            }
        }
    }
}
fun TR.insertUserRowCells(user: User) {
    td {
        classes = setOf("p-4 border-b border-blue-gray-50")
        div {
            classes = setOf("flex items-center gap-3")
            img {
                classes = setOf("relative inline-block h-9 w-9 !rounded-full object-cover object-center")
                src = "/img/placeholder.png"
            }
            p {
                classes = setOf("block font-sans text-sm antialiased font-normal leading-normal text-blue-gray-900")
                +"${user.firstName} ${user.lastName}"
            }
        }
    }
    td {
        classes = setOf("p-4 border-b border-blue-gray-50")
        div {
            classes = setOf("w-max")
            div {
                val enabledLabel = if (user.enabled) "Enabled" else "Disabled"
                val labelColor = if (user.enabled) "green" else "red"
                classes =
                    setOf("relative grid items-center px-2 py-1 font-sans text-xs font-bold text-black-900 uppercase rounded-md select-none whitespace-nowrap bg-$labelColor-500/20")
                span { +enabledLabel }
            }
        }
    }
    td {
        classes = setOf("p-4 border-b border-blue-gray-50")
        p {
            classes = setOf("block font-sans text-sm antialiased font-normal leading-normal text-blue-gray-900")
            +user.createdAt.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
        }
    }
    td {
        classes = setOf("p-4 border-b border-blue-gray-50")
        button {
            classes =
                setOf("cursor-pointer relative h-10 max-h-[40px] w-10 max-w-[40px] select-none rounded-lg text-center align-middle font-sans text-xs font-medium uppercase text-gray-900 transition-all hover:bg-gray-900/10 active:bg-gray-900/20 disabled:pointer-events-none disabled:opacity-50 disabled:shadow-none")
            attributes["hx-delete"] = "/users/${user.id}"
            attributes["hx-swap"] = "outerHTML"
            attributes["hx-target"] = "closest tr"
            unsafe {
                +"""
                    <span class="absolute transform -translate-x-1/2 -translate-y-1/2 top-1/2 left-1/2">
                        <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
                             stroke-width="2" stroke="currentColor" class="w-6 h-6">
                            <path stroke-linecap="round" stroke-linejoin="round"
                                  d="M6 18L18 6M6 6l12 12"/>
                        </svg>
                    </span>
                """.trimIndent()
            }
        }
    }
}

And here, apart from the CSS classes, we also added the X icon with the unsafe function from Kotlin HTML DSL:

unsafe {
    +"""
        <span class="absolute transform -translate-x-1/2 -translate-y-1/2 top-1/2 left-1/2">
            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
                 stroke-width="2" stroke="currentColor" class="w-6 h-6">
                <path stroke-linecap="round" stroke-linejoin="round"
                      d="M6 18L18 6M6 6l12 12"/>
            </svg>
        </span>
    """.trimIndent()
}

And voila! When we run the application now, we should see a pretty decent-looking UI😉

Summary

That’s all for this tutorial on how to work with htmx and Kotlin HTML DSL in Ktor.

Again, if you are tired of wasting your time looking for good Ktor resources, then check out my Ktor Server Pro course:

▶️ Over 15 hours of video content divided into over 130 lessons

🛠️ Hands-on approach: together, we implement 4 actual services

✅ top technologies: you will learn not only Ktor, but also how to integrate it with modern stack including JWT, PostgreSQL, MySQL, MongoDB, Redis, and Testcontainers.

Lastly, you can find the source code for this lesson in this GitHub repository.

The post A Quick Guide to htmx in Kotlin appeared first on Codersee blog- Kotlin on the backend.

Video Tutorial

If you prefer video content, then check out my video:

Quick Ktor Setup

As the first step, let’s quickly prepare a basic Ktor application responding with HTML.

To do so, let’s navigate to the https://start.ktor.io page and configure the artifact first:

The choice is up to you here. From my end, I will be using the latest Ktor version with the YAML config and without the version catalog.

Then, let’s add the Kotlin HTML DSL plugin necessary for our simple example:

Lastly, let’s download the zip package, extract it, and import it to our IDE.

If you are working in IntelliJ IDEA, then please make sure that you use JDK 23, too.

You can do that in two places:

• Settings -> Build, Execution, Deployment -> Build Tools -> Gradle. Here, please set the Gradle JVM to 23
• Project Structure -> Project Settings -> Project. On this page, please set the SDK to 23 and Language level to “SDK default”

After all, please sync the gradle project and wait for the process to finish.

Expose Endpoint Returning HTML

With all of that done, let’s delete the unwanted files that were generated automatically, like Routing.kt, or Templating.kt and expose the endpoint:

fun Application.module() {

    routing {
        get("/") {
            call.respondHtml {
                body {
                    + "Hello world!"
                }
            }
        }
    }

}

As we can see, whenever we reach the root path (by default, the localhost:8080), we should see the “Hello world!” text.

The Problem

Now, let’s change the text, for example, to contain only a “Hello!” message.

What happens if we refresh the page? Nothing! The page does not reflect our code change until we restart the server manually!

And, especially when dealing with HTML, it may become a pretty tedious task.

Solution- Ktor auto-reload

It won’t be a big surprise if I say that the Ktor auto-reload feature may be a great solution here? 😉

But what is that?

Well, long story short, it its a feature that we can turn on by enabling the development mode in Ktor. And when enabled, it reloads application classes on code changes.

To be more specific, according to the documentation, Ktor listens for the changes to the following files:

/build/classes/kotlin/main/META-INF
/build/classes/kotlin/main/com/your-package-namn
/build/classes/kotlin/main/com
/build/classes/kotlin/main
/build/resources/main

And as we can see, by the code changes, we mean the generated outputs and artifacts. But the good news is that with gradle, we can easily automate the generation, too.

Lastly, I just wanted to mention that application logs are also pretty clear about what we need to do in order to enable auto-reload:

2025-03-25 06:40:49.929 [main] INFO  Application - Autoreload is disabled because the development mode is off.
2025-03-25 06:40:50.072 [main] INFO  Application - Application started in 0.374 seconds.
2025-03-25 06:40:50.363 [DefaultDispatcher-worker-2] INFO  Application - Responding at http://127.0.0.1:8080

Enable development mode

With all of that said, let’s get back to the practice part.

As the first step, we must enable the development mode. And we can do that in a few ways, so let me walk you through them.

Hardcoded Approach

When we navigate to the build.gradle.kts file, we should see the following:

application {
    mainClass = "io.ktor.server.netty.EngineMain"

    val isDevelopment: Boolean = project.ext.has("development")
    applicationDefaultJvmArgs = listOf("-Dio.ktor.development=$isDevelopment")
}

So the easy and the dummy approach would be to simply hardcode the value- -Dio.ktor.development=true:

application {
    mainClass = "io.ktor.server.netty.EngineMain"
    applicationDefaultJvmArgs = listOf("-Dio.ktor.development=true")
}

Now, when we run the app with ./gradlew run, we will see that the message disappeared, proving the development mode is enabled:

2025-03-25 07:10:15.883 [main] INFO  Application - Application started in 0.41 seconds.
2025-03-25 07:10:16.142 [main] INFO  Application - Responding at http://127.0.0.1:8080
<==========---> 83% EXECUTING [1m 13s]

But first, this approach does not work if you run the server in IntelliJ by using the green icon because, by default, it does not invoke any gradle command.

Secondly, it is hardcoded, meaning we don’t have too much control over it in various environments.

Program Argument

Another option is to bring back what we already had in the build.gradle.kts:

val isDevelopment: Boolean = project.ext.has("development")
applicationDefaultJvmArgs = listOf("-Dio.ktor.development=$isDevelopment")

And from now on, the only thing we need is the -Pdevelopment flag for the gradlew run command:

./gradlew run -Pdevelopment

It’s clearly better and gives us more flexibility.

VM options

Another option that we have on the table is to directly use the VM option we saw above- -Dio.ktor.development=true.

For that purpose, we can even completely get rid of the previous snippet from application in build.gradle.kts:

application {
    mainClass = "io.ktor.server.netty.EngineMain"
}

And now, whenever invoking the gradlew run command, we will simply put the whole arg:

./gradlew "-Dio.ktor.development=true" run

Moreover, when working with IntelliJ, we can edit our configuration to pass the same option:

So we can see that this option will work with both gradle, as well as the IntelliJ IDEA runs.

Config File

Lastly, we can also set that in the application.yaml:

ktor:
    development: true
    application:
        modules:
            - com.codersee.ApplicationKt.module
    deployment:
        port: 8080

It works exactly the same, and with environment variables can give us a lot of flexibility, too.

Automate Build

Alright, so at this point, our app is up and running with the development mode ON.

However, when we make any code change, nothing still happens!

Well, as I mentioned previously, the Ktor auto-reload feature looks for the output files. Meaning we must build the project to see the changes.

And we can do that by either running the ./gradlew build or by navigating to the Build tab in IntelliJ:

And although this works and we can now see changes without the restart, it is still not too convenient.

Well, the good news we can slightly adjust the gradlew build command and automate that:

./gradlew -t build -x test

With the -t flag (or --continuous), we enable the continuous build mode. Gradle will watch for changes in the source files, and whenever a relevant change is detected, it will automatically rerun the build task.

Additionally, we exclude the test task using the -x flag to speed up the process a little 🙂

If we would like to add that as a run configuration to IntelliJ, then it is really easy, too:

And basically, that’s all! At this point, we can add the necessary HTML changes without restarting the Ktor server.

Narrowing Down Watched Files

As I mentioned above, Ktor listens for the file updates in the following directories:

/build/classes/kotlin/main/META-INF
/build/classes/kotlin/main/com/your-package-namn
/build/classes/kotlin/main/com
/build/classes/kotlin/main
/build/resources/main

If we would like to narrow down the list of watched directories, then we can do that, for example, in the YAML config file:

ktor:
    deployment:
        watch:
            - resources

The only thing we must specify is the part of the watched patch that we want to keep.

Summary

And that’s all for this quick tutorial on how to enable the auto-reload feature in Ktor.

If you found this content useful, then check out my Ktor Server Pro course– the most comprehensive Ktor course on the market.

Thank you for being here, and see you around! 🙂

The post Auto-reload in Ktor appeared first on Codersee blog- Kotlin on the backend.

Note: this article was created based on one of the services we implement in my Ktor Server Pro course. If you would like to learn how to expose a fully functional REST API, secure the application, and many many more, then don’t hesitate and secure your spot today😉

Before we start, I just wanted to mention that at the moment of writing KMongo is officially deprecated! Maybe you saw my previous article, maybe you saw some outdated content in some other places. Either way, we should not use that library anymore in favor of the official driver that comes in two flavors:

• MongoDB Kotlin Driver (for applications using coroutines)
• MongoDB Kotlin Sync Driver (for apps that require synchronous processing)

Video Content

As always, if you prefer a video content, then please check out my latest YouTube video:

Create & Verify MongoDB Instance

If you already have a MongoDB instance installed on your machine, feel free to skip this step.

On the other hand, if that is not the case, you can install it using the official manual. Or, if you just like me have a Docker environment, you can run the following command:

docker run --name my_awesome_mongo_name -d -p 27017:27017 mongo:8.0.4

This way, we run the Mongo docker container and expose it’s port 27017 .

And to verify it running, we can run the docker ps :

CONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS          PORTS                      NAMES
9ecd8986ac34   mongo:8.0.4   "docker-entrypoint.s…"   20 seconds ago   Up 19 seconds   0.0.0.0:27017->27017/tcp   my_awesome_mongo_name

As we can see, it was created successfully and we should be able to connect to it at localhost:27017

We can assert that, as well, for example with a free and official tool- MongoDB Compass:

And if we are able to connect, it means that we can head to the next step.

Create a New Ktor Project

Nextly, let’s navigate to the Ktor Project Generator page to create a fresh project from scratch.

If you use the IntelliJ Ultimate Edition, then you can generate it in your IDE

As we can see, we will be using Ktor 3.1.0 with Netty and configuration in the YAML file.

The important thing to mention here is that if we want to work with Kotlin coroutines, we should not select the below MongoDB plugin:

Because as we can see, this adds the MongoDB Kotlin Sync Driver for synchronous processing:

So, in our case, to keep our Ktor application as vanilla as possible, we will not add any additional plugins.

With that done, let’s hit the Download button and let’s import the project to our IDE.

Add MongoDB Async Driver to Ktor

Before adding the necessary import, let’s perform a small cleanup.

Firstly, let’s remove the Routing.kt file- we don’t need it for this tutorial.

Then, let’s navigate to the Application.kt and let’s get rid of routing config, as well. Eventually, we should have something like that:

 package com.codersee

import io.ktor.server.application.*

fun main(args: Array<String>) {
    io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {}

With that done, let’s add the MongoDB Kotlin Driver to work with coroutines.

During the configuration, we decided to use the Gradle version catalog. So now, we must navigate to the libs.versions.toml inside the gradle directory and add the mongodb-version along with mongodb-driver-kotlin:

[versions]
kotlin-version = "2.1.10"
ktor-version = "3.1.0"
logback-version = "1.4.14"
mongodb-version = "5.3.1"

[libraries]
ktor-server-core = { module = "io.ktor:ktor-server-core-jvm", version.ref = "ktor-version" }
ktor-server-netty = { module = "io.ktor:ktor-server-netty", version.ref = "ktor-version" }
logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback-version" }
ktor-server-config-yaml = { module = "io.ktor:ktor-server-config-yaml", version.ref = "ktor-version" }
ktor-server-test-host = { module = "io.ktor:ktor-server-test-host", version.ref = "ktor-version" }
kotlin-test-junit = { module = "org.jetbrains.kotlin:kotlin-test-junit", version.ref = "kotlin-version" }
mongodb-driver-kotlin = { module = "org.mongodb:mongodb-driver-kotlin-coroutine", version.ref = "mongodb-version" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin-version" }
ktor = { id = "io.ktor.plugin", version.ref = "ktor-version" }

With that done, let’s navigate to build.gradle.kts and add the following line:

implementation(libs.mongodb.driver.kotlin)

Lastly, let’s sync the gradle project so that the necessary libraries are fetched.

Introduce Model Classes

Before we can start working with coroutines, we must prepare classes that will be translated into Mongo documents and vice versa.

To do so, let’s create the Product.kt class and put the following:

import org.bson.codecs.pojo.annotations.BsonId
import org.bson.types.ObjectId

data class Product(
    @BsonId
    val id: ObjectId? = null,
    val name: String,
    val description: String,
    val price: Double,
    val category: ProductCategory,
    val tags: List<ProductTag>,
)

enum class ProductCategory {
    VIDEO_GAMES, TOOLS, HOME_AND_KITCHEN, FOOD
}

enum class ProductTag {
    EXCLUSIVE, HANDMADE, ORGANIC, BESTSELLER
}

As we can see, all fields except the id field are plain Kotlin classes. And later, they will be serialized/deserialized 1:1 when saving and retrieving from the database.

When it comes to the id field, we mark it using the @BsonId annotation. Thanks to that, it will be serialized to the _id BSON field that represents a primary key of our document. Moreover, we assign a default null value to it. This way, the value will be generated automatically.

Configure Ktor Connection to MongoDB

As the next step, let’s connect our Ktor application to the Mongo instance.

And for that purpose, let’s navigate to Application.kt and implement the following logic:

fun Application.module() {
    val settings = MongoClientSettings.builder()
        .applyConnectionString(
            ConnectionString("mongodb://localhost:27017")
        )
        .build()

    val client = MongoClient.create(settings)
    val database = client.getDatabase("application")
    val productCollection = database.getCollection<Product>("products")
}

Firstly, we instantiate the MongoClientSettings builder. A builder that allows us to configure the connection string for our database. Additionally, if you are looking for more configuration options, like reads or writes repetition, then you should start in there.

Then, we create a new client and pass our settings to it. If you would like to, then you could use another variant of the create function that takes the connection String as an argument:

public fun create(connectionString: String): MongoClient

But, in my opinion, using the builder approach is a better choice in terms of extensibility.

With that done, we get the instance of our database, by passing its name. Lastly, we obtain the MongoCollection that we will be injecting later into the product repository. Again, we pass the name of our collection, too.

To verify, let’s run our application.

As a result, we should see the following text in the logs indicating that everything is perfectly fine:

[cluster-ClusterId{value='67bd5f4689251d25d5077fb7', description='null'}-localhost:27017] INFO  org.mongodb.driver.cluster - Monitor thread successfully connected to server with description ServerDescription{address=localhost:27017, type=STANDALONE, cryptd=false, state=CONNECTED, ok=true, minWireVersion=0, maxWireVersion=25, maxDocumentSize=16777216, logicalSessionTimeoutMinutes=30, roundTripTimeNanos=26289200, minRoundTripTimeNanos=0}

MongoDB Coroutines CRUD Operations

After we did all of that preparation, we can finally create the ProductRepository class:

class ProductRepository(
    private val productCollection: MongoCollection<Product>,
) { }

And inject the collection in Application.kt :

val productRepository = ProductRepository(productCollection)

The constructor injection is a great way to make our code easier to test in the future.

Anyway, coming back to the topic, let’s learn how we can how we can perform basic CRUD operations with coroutines.

Persits Products

Initially, our products collection is empty, so let’s add the following code to start populating it:

suspend fun save(product: Product): Product? {
    val result = productCollection.insertOne(product)

    return result.insertedId
        ?.let { product.copy(id = it.asObjectId().value) }
}

First of all, we must make our function suspend. Why? Because the insertOne we use is a suspend function, so we must invoke it either from the coroutine or another suspend function.

When it comes to the persisting- the function that we use returns the InsertOneResult that allows us to either get a boolean informing if the write was acknowledged or the generated identifier of the saved product. And in my opinion, reading that and returning a Product instance with the updated field is a quite nice approach.

After that, let’s get back to the Application.kt and test this function:

val saved = runBlocking {
    productRepository.save(
        Product(
            name = "Product 1",
            description = "Description 1",
            price = 19.99,
            category = ProductCategory.TOOLS,
            tags = listOf(ProductTag.EXCLUSIVE, ProductTag.BESTSELLER)
        )
    )
}

println(saved)

I know, the good, old println 🤠

Anyway, if we run our application, we should see the following in the logs:

Product(id=67bd62f974edd96bbd59874a, name=Product 1, description=Description 1, price=19.99, category=TOOLS, tags=[EXCLUSIVE, BESTSELLER])

Additionally, when we hit the refresh button in MongoDB Compass, we should see the following:

And this proves that not only the Product was saved. But also, the application database and products collection was created by our client automatically.

Find By ID

Nextly, let’s implement the function to fetch product by identifier:

suspend fun findById(id: String): Product? {
    val objectId = ObjectId(id)

    return productCollection.find(
        eq("_id", objectId)
    ).firstOrNull()
}

This time, we use the find method. And this function returns the FindFlow which is the Flow implementation for find operations.

This function allows us to pass filters as arguments to it. And to get the particular product, we use the eq filter. One of the many filters that we can find in com.mongodb.client.model.Filters. We must remember that our identifier is of the ObjectId type, so we create a new instance from our String value.

Lastly, we invoke the firstOrNull– the terminal operator that returns the first element emitted by the flow and then cancels flow’s. We leverage the fact that only one element with such an identifier can be found in our database.

So with all of that done, let’s get back to the Application.kt and test this function:

val found = runBlocking {
    productRepository.findById("67bd62f974edd96bbd59874a")
}

val notFound = runBlocking {
    productRepository.findById("67bd62f974edd96bbd59874b")
}

// Logs: 

// Product(id=67bd62f974edd96bbd59874a, name=Product 1, description=Description 1, price=19.99, category=TOOLS, tags=[EXCLUSIVE, BESTSELLER])

// null

As we can see, our test proves that findById not only works but also it simply returns null when nothing was found. No unexpected exceptions, etc.

Updating Products

As the next step, let’s add the function responsible for updating products:

suspend fun update(id: String, product: Product): Product? {
    val objectId = ObjectId(id)

    return productCollection.findOneAndReplace(
        filter = eq("_id", objectId),
        replacement = product,
        options = FindOneAndReplaceOptions().returnDocument(ReturnDocument.AFTER)
    )
}

Again, this function is a suspended function, and again we use the same combination of the eq filter and ObjectId to find the item we are interested in.

The function that we use- findOneAndReplace– allows us to simply replace the existing document by passing a new version. Nevertheless, by default, this function returns the object before the update! And in my opinion, it makes more sense to return the updated versions in this case. And that’s why we specify the additional option.

As a note: if you would like to update just some fields, then the findOneAndUpdate may be a better choice.

With all of that done, let’s test our functionality:

val updated = runBlocking {
    productRepository.update(
        id = "67bd62f974edd96bbd59874a",
        product = Product(
            name = "Updated Product 1",
            description = "Updated Description 1",
            price = 20.11,
            category = ProductCategory.FOOD,
            tags = listOf(ProductTag.BESTSELLER)
        )
    )
}

val notUpdated = runBlocking {
    productRepository.update(
        id = "67bd62f974edd96bbd59874b",
        product = Product(
            name = "Updated Product 2",
            description = "Updated Description 3",
            price = 20.11,
            category = ProductCategory.FOOD,
            tags = listOf(ProductTag.BESTSELLER)
        )
    )
}

// Logs: 

// Product(id=67bd62f974edd96bbd59874a, name=Updated Product 1, description=Updated Description 1, price=20.11, category=FOOD, tags=[BESTSELLER])

// null

As we can see, everything works as expected. Our function returns the updated product. And moreover, it does not throw any exceptions when a product is not found!

Delete Products

Nextly, let’s take a look at how we can remove products from our database:

suspend fun deleteById(id: String): Boolean {
    val objectId = ObjectId(id)

    val deleteResult = productCollection.deleteOne(
        eq("_id", objectId)
    )

    return deleteResult.deletedCount == 1L
}

At this point of our MongoDB coroutines tutorial, I think the code is quite descriptive. We use the same pattern we did previously to find by ID and we utilize the function from DeleteResult to get the count of deleted items.

Of course, given we have only one item with a particular _id, the function returns true only if the count is equal to one.

And again, a small note from my end if you would like to return the deleted product instead, then you can use the findOneAndDelete instead.

I will skip the testing part here, you must trust me 😀

Case-insensitive Search In MongoDB

As the last step, I will show you how to utilize the function that we already know (find) to perform a case-insensitive search in MongoDB:

fun find(
    title: String,
): Flow<Product> {
    return productCollection.find(
        regex(Product::name.name, title, "i")
    )
}

As we can see, this time we make use of the regex function, that will add the… regex filter 😀 And thanks to the “i” option, the whole search will be case-insensitive.

Additionally, we make use of the name field reference. We could use a simple String value- “name”- but thanks to our approach we won’t need to remember to manually update the name in case of the update.

Lastly, I just wanted to mention here that this is one of the approaches to tackle this issue. According to the Mongo docs, we have also two more options:

1. Create a case-insensitive index with a collation strength of 1 or 2, and specify that your query uses the same collation.
2. Set the default collation strength of your collection to 1 or 2 when you create it, and do not specify a different collation in your queries and indexes.

Adding Sorting and Pagination to Search Results

Lastly, let’s make a small adjustment to add pagination and sorting to our logic.

To do so, let’s implement the Order Enum first:

enum class Order {
    ASC, DESC
}

And with that done, let’s get back to our repository:

fun find(
    title: String,
    sortBy: String,
    order: Order,
    limit: Int,
    skip: Int,
): Flow<Product> {
    val sort = when (order) {
        Order.ASC -> ascending(sortBy)
        Order.DESC -> descending(sortBy)
    }

    return productCollection.find(
        regex(Product::name.name, title, "i")
    )
        .sort(sort)
        .limit(limit)
        .skip(skip)
}

As we can see, our function allows us to pass 4 more arguments during the invocation: sortBy, order, limit, and skip.

So from now on, we can not only perform the search but also set the limit of results, ordering, as well as the order of items.

Summary

And that’s all for this tutorial on how to work with MongoDB and Kotlin coroutines in Ktor.

I hope you enjoyed it, and if you would like to learn more Ktor concepts in a fully hands-on manner, then check out my course.

Lastly, if you would like to get the whole codebase, then you can find it in this GitHub repository.

The post MongoDB with Kotlin Coroutines in Ktor appeared first on Codersee blog- Kotlin on the backend.

Ktor is a flexible library that provides the ability to create a non-blocking HTTP client, which enables you to perform requests and handle responses. Its functionality could be enhanced with plugins, such as logging, serialization, authentication, and so on. Its core benefit is that it’s a lightweight framework that can be used on different platforms such as Android, JVM, or Native!

General Overview

Let’s discuss some basic information for everyone to be on the same page.

Today, we are going to write HTTP requests and receive responses. There are different types of requests but OpenWeatherMap for the most part utilizes GET requests with various parameters.

OpenWeatherMap API, as you can tell by its name, is an API for retrieving weather-related data. It provides various types of data but we’re going to use only 3 of them:

• Current Weather,
• 3-hours Forecast,
• and Air Pollution API.

To start using OpenWeatherMap you need to register and get your special API key. It has lots of free options and for our sake, we don’t need to pay at all.

But be aware of the limitations of the call: 1,000 API calls per day for free!

Gradle Dependencies

For this project, we’re going to use basic Ktor’s client, serialization, engines, and logging.

Your build.gradle.kts file would look like this:

val ktor_version: String by project
val kotlin_version: String by project
val logback_version: String by project

plugins {
    kotlin("jvm") version "1.9.21"
    id("io.ktor.plugin") version "2.3.6"
    id("org.jetbrains.kotlin.plugin.serialization") version "1.9.21"
    application
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.ktor:ktor-client-core-jvm")
    implementation("io.ktor:ktor-client-cio-jvm")

    implementation("io.ktor:ktor-serialization-kotlinx-json-jvm")
    implementation("io.ktor:ktor-client-content-negotiation-jvm")

    implementation("ch.qos.logback:logback-classic:$logback_version")
    implementation("io.ktor:ktor-client-logging:$ktor_version")
    implementation("io.ktor:ktor-client-apache5:$ktor_version")

    testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version")
}

Creating Models

The first step of creating a Ktor client is actually revealing what we’re gonna handle. Basically, we need 2 types of models: request and response. All necessary information is located on the corresponding page of the documentation. The documentation is pretty neat and, generally, it’s a good practice to check it out during the coding!

To optimize the process we could spot similar parameters appearing in the Current Weather and Weather Forecast. Such as Mode and Units.

So we can create separate classes and use the latter like this:

enum class ResponseUnits {
    STANDARD,
    METRIC,
    IMPERIAL
}

enum class ResponseMode {
    XML
}

Now let’s create the request themselves.

As there are some optional parameters present we’re going to make them nullable with default value null so that we could use them or not with ease.

Here are the models for requests:

data class CurrentWeatherRequest(
    val latitude: Double,
    val longitude: Double,
    val mode: ResponseMode? = null,
    val units: ResponseUnits? = null,
    val language: String? = null
)

data class WeatherForecastRequest(
    val latitude: Double,
    val longitude: Double,
    val mode: ResponseMode? = null,
    val units: ResponseUnits? = null,
    val language: String? = null,
    val count: Int? = null
)

data class AirPollutionRequest(
    val latitude: Double,
    val longitude: Double
)

Consequently, we desperately need models to put our data to: the response models.

It’s the most routine process because there are some huge responses and by ‘huge’ I mean lots of parameters. Let’s dive deep into one model and the rest would be easy to create.

Here’s what our JSON of current weather data looks like (there is also a text representation of this JSON with more information about parameters):

{
  "coord": {
    "lon": 10.99,
    "lat": 44.34
  },
  "weather": [
    {
      "id": 501,
      "main": "Rain",
      "description": "moderate rain",
      "icon": "10d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 298.48,
    "feels_like": 298.74,
    "temp_min": 297.56,
    "temp_max": 300.05,
    "pressure": 1015,
    "humidity": 64,
    "sea_level": 1015,
    "grnd_level": 933
  },
  "visibility": 10000,
  "wind": {
    "speed": 0.62,
    "deg": 349,
    "gust": 1.18
  },
  "rain": {
    "1h": 3.16
  },
  "clouds": {
    "all": 100
  },
  "dt": 1661870592,
  "sys": {
    "type": 2,
    "id": 2075663,
    "country": "IT",
    "sunrise": 1661834187,
    "sunset": 1661882248
  },
  "timezone": 7200,
  "id": 3163858,
  "name": "Zocca",
  "cod": 200
}

Now we have to face some difficulties. Not only do we have to parse it but also there are some optional parameters.

To solve the first issue we mark our classes with @Serializable and @SerialName annotations. I highly recommend using @SerialName because it provides enhanced readability and usability especially when handling such long classes.

To solve the second problem I recommend you to read my detailed guide that covers all essential information about Serialization. Basically, if we want to parse all of the data, we make optional fields with @EncodeDefault and make it nullable with the default value as null. This makes sure that if there was no such a field we would get a null, without any exceptions.

Now let’s look at classes for our Ktor client:

@OptIn(ExperimentalSerializationApi::class)
@Serializable
data class CurrentWeather(
    @SerialName("coord") val coordinates: Coordinates,
    @SerialName("weather") val weather: List<Weather>,
    @SerialName("base") val base: String,
    @SerialName("main") val main: Main,
    @SerialName("visibility") val visibility: Int,
    @SerialName("wind") val wind: Wind,
    @SerialName("rain")
    @EncodeDefault
    val rain: Rain? = null,
    @SerialName("snow")
    @EncodeDefault
    val snow: Snow? = null,
    @SerialName("clouds") val clouds: Clouds,
    @SerialName("dt") val dateTime: Long,
    @SerialName("sys") val systemData: SystemData,
    @SerialName("timezone") val timezone: Int,
    @SerialName("id") val cityId: Int,
    @SerialName("name") val cityName: String,
    @SerialName("cod") val code: Int
) {

    //other classes here

    @Serializable
    data class Wind(
        @SerialName("speed") val speed: Double,
        @SerialName("deg") val direction: Int,
        @SerialName("gust") val gust: Double
    )

    @Serializable
    data class Rain(
        @SerialName("1h")
        @EncodeDefault
        val oneHour: Double? = null,
        @SerialName("3h")
        @EncodeDefault
        val threeHours: Double? = null
    )

	//other classes here
}

The rest of the responses are quite similar so you could check them out in the repository that comes with this article.

Quick remark, I’ve made classes such as Coordinates, Weather, etc. as inner classes since there are the same classes for other responses but with different structures.

This approach helps not to mix them up.

Creating The Ktor Client Itself

We are gonna be using Ktor’s HttpClient with some adjustments and extended configuration.

Let’s check it out:

private val client = HttpClient(Apache5) {
        install(ContentNegotiation) {
            json(Json {
                isLenient = false
            })
        }
        install(Logging)
        defaultRequest {
            url {
                protocol = URLProtocol.HTTPS
                host = "api.openweathermap.org/data/2.5"
            }
        }
    }

First of all, we have the Apache5 engine rather than CIO, for example, because it’s suitable for HTTP/2 while CIO is not.

Next, we have 2 plugins: the ContentNegotiation for the JSON parsing and the Logging for detailed logs.

Also, as all of our requests to OpenWeatherMap have similar endpoints, we can use defaultRequest to shorten our request’s links. The whole defaultRequest translates to https://api.openweathermap.org/data/2.5/. We’ll combine this with the request’s specific parameters.

Now let’s talk about them.

Creating Routes

As all of our routes would share similar logic let’s look closely at only one of them for the Current Weather:

suspend fun getCurrentWeather(currentWeatherRequest: CurrentWeatherRequest): CurrentWeather? {
        return try {
            val response: HttpResponse = client
                .get("/weather") {
                    url {
                        parameters.append("lat", currentWeatherRequest.latitude.toString())
                        parameters.append("lon", currentWeatherRequest.longitude.toString())
                        parameters.append("appid", APP_ID)
                        if (currentWeatherRequest.mode != null) parameters.append(
                            "mode",
                            currentWeatherRequest.mode.name()
                        )
                        if (currentWeatherRequest.units != null) parameters.append(
                            "units",
                            currentWeatherRequest.units.name()
                        )
                        if (currentWeatherRequest.language != null) parameters.append(
                            "lang",
                            currentWeatherRequest.language
                        )
                    }
                }

            if (response.status == HttpStatusCode.OK) {
                response.body<CurrentWeather>()
            } else {
                println("Failed to retrieve current weather. Status: ${response.status}")
                null
            }
        } catch (e: Exception) {
            println("Error retrieving current weather: ${e.message}")
            null
        }
    }

Here we create GET HttpResponse with the path “/weather” and then we specify additional parameters, note that it’ll automatically use the correct notation(? and other).

In the URL block, we list all of our parameters using parameters.append() function that takes the name and the value. There is no need to include optional parameters that are not specified, so we simply check whether they’re null or not.

Our Ktor client also implements error handling.

For the errors with the request itself, such as connection problems, any issues from the server, etc. we’ll get the “Error retrieving current weather:” message and null result.

And if your request is successful but has some undesired response, in our case everything except 200 OK, we’ll get “Failed to retrieve current weather. Status:” and null result as well.

Ktor Client In Action

To use the client you could simply call our object with the corresponding method like this:

WeatherClient.getCurrentWeather(
        CurrentWeatherRequest(
            latitude = 44.34,
            longitude = 10.99,
            units = ResponseUnits.IMPERIAL,
            language = "pl"
        )
    )
	
	WeatherClient.getWeatherForecast(
        WeatherForecastRequest(
            latitude = 44.34,
            longitude = 10.99,
            units = ResponseUnits.IMPERIAL,
            language = "pl"
        )
    )
	
	WeatherClient.getAirPollution(
        AirPollutionRequest(
            latitude = 50.0,
            longitude = 50.0
        )
    )

This could be used on every platform but as I’ve mentioned before make sure you’re using the correct engine!

Summary

And that’s all for this article about the OpenWeatherMap API Ktor client.

If you would like to download the full source code, then you can find it in this GitHub repository.

Lastly, thank you for being here, and happy to hear your feedback in the comments section below!

The post How To Create a Ktor Client To Connect To OpenWeatherMap API appeared first on Codersee blog- Kotlin on the backend.

• Ktor Server
• Ktor Client
• WebSockets in Ktor

Before we start, I just wanted to note that we are going to use a modified project from the lesson about Ktor with Ktorm and PostgreSQL. So if you don’t know how to set up and use a Ktor server with PostgreSQL you should definitely check it up, because I will skip the basics. Additionally, if you’d like to explore kotlinx.serialization in details, then check out my detailed guide.

Lastly, please note that there is a GitHub repository for all of this in the end of this lesson!

Setup

A few quick words about setting up. Note that for the main thing we are going to use, such as ContentNegotiation, Ktor has different implementations for Client and Server.

Do not mess them up, it causes a lot of trouble and a lot of Stack Overflow questions 🙂

//server
implementation("io.ktor:ktor-server-content-negotiation-jvm")
//client
implementation("io.ktor:ktor-client-content-negotiation-jvm")

kotlinx.serialization With Ktor Server

Now, let’s start with the kotlinx.serialization for the Ktor server part.

I am going to use Postman for making HTTP requests and testing the server. You can use any tool for this purpose even the client we will write about in the next part 🙂

First of all, let’s check our classes for the User from previous parts:

interface User : Entity<User> {  
  companion object : Entity.Factory<User>()  
  
  val userId: Long?  
  var userName: String  
}

 Now we are going to need classes for our responses: 

@Serializable  
data class UserResponse(  
  val userId: Long,  
  val userName: String  
)  
  
@Serializable  
data class UserRequest(  
  val userName: String  
)

@Serializable  
data class UserErrorResponse(val message: String)

Basically, the central part of all serialization here is ContentNegotiation which could be installed for our server(not the client).

As we are using it for Json serialization, we should specify it as json() like this:

fun Application.configureSerialization() {  
  install(ContentNegotiation) {  
    json(Json {  
      prettyPrint = true  
      isLenient = true  
    })  
  }  
}

And here’s our loved Json object! Now we can do all kinds of trickery that we know and learned before.

For the code above, I’ve used a simple style specification, but you can use it as you like. As an example, we can add a custom or polymorphic serializer:

private val contextualSerializerModule = SerializersModule {
  contextual<Date>(DateAsStringSerializer)
}

private val polymorphicSerializationModule = SerializersModule {
  polymorphic(User::class) {
    subclass(Admin::class, Admin.serializer())
    subclass(Guest::class, Guest.serializer())
  }
}

object DateAsStringSerializer : KSerializer<Date> {
  private val dateFormat = SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ")

  override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor(
    "Date", 
    PrimitiveKind.STRING,
  )

  override fun serialize(encoder: Encoder, value: Date) {
    encoder.encodeString(dateFormat.format(value))
  }

  override fun deserialize(decoder: Decoder): Date {
    return dateFormat.parse(decoder.decodeString())
  }
}

And our server is going to look like this: 

fun Application.configureSerialization() {
  install(ContentNegotiation) {
    json(Json {
      prettyPrint = true
      isLenient = true
      serializersModule = contextualSerializerModule
      serializersModule = polymorphicSerializationModule
    })
  }
}

We can remove this for now, we’ll use actual polymorphic serialization in the Web Sockets section.

Now, what about routes? Let’s check out a simple POST request:

fun Route.createUser(userService: UserService) {
  post {

    val request = call.receive<UserRequest>()

    val success = userService.createUser(userRequest = request)

    if (success)
      call.respond(HttpStatusCode.Created)
    else
      call.respond(HttpStatusCode.BadRequest, UserErrorResponse("Cannot create user"))
  }
}

As we can see, we don’t serialize/deserialize anything manually.

The whole process happens due to this line:

val request = call.receive<UserRequest>()

We can witness that our request deserializes into the UserRequest as such is marked with @Serializable annotation.

The same happens here:

fun Route.updateUserByIdRoute(userService: UserService) {
  patch("/{userId}") {
    val userId: Long = call.parameters["userId"]?.toLongOrNull()
      ?: return@patch call.respond(
          HttpStatusCode.BadRequest, 
          UserErrorResponse("Invalid id")
        )

    val request = call.receive<UserRequest>()
    val success = userService.updateUserById(userId, request)

    if (success)
      call.respond(HttpStatusCode.NoContent)
    else
      call.respond(
        HttpStatusCode.BadRequest,
        UserErrorResponse("Cannot update user with id [$userId]"),
      )
  }
}

Our request is deserialized and we can update a user.

Now let’s test it and get our users:

private fun User?.toUserResponse(): UserResponse? =  
    this?.let { UserResponse(it.userId!!, it.userName) }

fun Route.getAllUsersRoute(userService: UserService) {  
    get {  
        val users = userService.findAllUsers()  
            .map(User::toUserResponse)  
  
        call.respond(message = users)  
    }  
}

As I said before, I’m going to use Postman.

So how about checking our server:

Post:

Delete:

kotlinx.serialization With Ktor Client

Now the kotlinx.serialization for the Ktor client. Here’s the same thing, but make sure you don’t miss anything and use ContentNegotiation FOR CLIENT.

Check the import:

import io.ktor.client.plugins.contentnegotiation.*

We can install it just like before:

private val client = HttpClient(CIO) {
  install(ContentNegotiation) {
    json(Json {
      prettyPrint = true
      isLenient = true
    })
  }
  defaultRequest {
    url {
      host = "0.0.0.0"
      path("/")
      port = 8080
    }
  }}

All things apply here as well, so let’s check how to use it for our requests. There are lots of possible situations, we are going to cover basic data retrieving and how to place something inside a body of a request.

We want to get all of the users, what should we do? We can use something like this:

suspend fun getAllUsers(): List<UserResponse> {
  return try {
    val response: HttpResponse = client.get("/users")

    if (response.status == HttpStatusCode.OK) {
      response.body<List<UserResponse>>()
    } else {
      println("Failed to retrieve users. Status: ${response.status}")
      emptyList()
    }
  } catch (e: Exception) {
    println("Error retrieving users: ${e.message}")
    emptyList()
  }
}

The main part here as well is this:

response.body<List<UserResponse>>()

The UserResponse class can be serialized, and we don’t need to do anything at all. All hail the ContentNegotiation 🙂

How about we create some user? We can do it as well:

suspend fun createUser(user: UserRequest) {
  try {
    val response: HttpResponse = client.post("/users") {
      contentType(ContentType.Application.Json)
      setBody(user)
    }

    if (response.status == HttpStatusCode.Created) {
      println("User created successfully")
    } else {
      println("Failed to create user. Status: ${response.status}")
    }
  } catch (e: Exception) {
    println("Error creating user: ${e.message}")
  }
}

This time, we specify the content type for our body, such as ContentType.Application.Json and just set our user in here. All happens as it is a miracle.

Now let’s test it. I’m going to use this simply to check each method:

runBlocking {

  val allUsersOld = UserRequests.getAllUsers()
  println("All Users: $allUsersOld")

  val newUser = UserRequest(
    userName = "Mark"
  )

  UserRequests.createUser(newUser)

  val allUsersNew = UserRequests.getAllUsers()
  println("All Users: $allUsersNew")

  val userIdToRetrieve = 2L
  val retrievedUser = UserRequests.getUserById(userIdToRetrieve)
  println("User with ID $userIdToRetrieve: $retrievedUser")

  val userIdToUpdate = 2L
  val updatedUser = UserRequest(
    userName = "Bob"
  )
  UserRequests.updateUserById(userIdToUpdate, updatedUser)

  val userIdToDelete = 2L
  UserRequests.deleteUserById(userIdToDelete)
}

And the corresponding result would be something like this:

...
All Users: [UserResponse(userId=2, userName=User #2)]
...
User created successfully
...
All Users: [UserResponse(userId=2, userName=User #2), UserResponse(userId=7, userName=Mark)]
...
User with ID 2: UserResponse(userId=2, userName=User #2)
...
User updated successfully
...
User deleted successfully

I’ve skipped the logs because they are not important for this. 

Web Sockets

So, here’s the fun part. There is no Content Negotiation for the Web Sockets 🙁

Nonetheless, there is such thing as contentConverter for WebSockets:

private val client = HttpClient(CIO).config {
  install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(
      Json
    )
  }
}

Basically, that’s it, now we can use sendSerialized() and receiveDeserialized() to send and receive data.

However, let’s focus more on manual implementation for the sake of understanding. Here we have classes to represent our messages:

@Serializable
abstract class Message {
  abstract val content: String
}

@Serializable
@SerialName("text")
class TextMessage(override val content: String) : Message()

@Serializable
@SerialName("system")
class SystemMessage(override val content: String, val systemInfo: String) : Message()

private val module = SerializersModule {
  polymorphic(Message::class) {
    subclass(TextMessage::class, TextMessage.serializer())
    subclass(SystemMessage::class, SystemMessage.serializer())
  }
}

val messagesFormat = Json {
  serializersModule = module
}

We are going to use TextMessage to send to the server and SystemMessage to send back from the server.

To send a message we must serialize it to string. And to receive vice versa. Nothing difficult: 

@OptIn(ExperimentalSerializationApi::class)
private suspend fun DefaultClientWebSocketSession.receiveMessage() {
  try {
    for (message in incoming) {
      message as? Frame.Text ?: continue
      val deserializedMessage: Message =
        messagesFormat.decodeFromStream(message.data.inputStream())
      println("${deserializedMessage.content} // ${(deserializedMessage as? SystemMessage)?.systemInfo}")
    }
  } catch (e: Exception) {
    println("Error while receiving: " + e.localizedMessage)
  }
}

private suspend fun DefaultClientWebSocketSession.sendMessage(message: Message) {
  val serializedMessage = messagesFormat.encodeToString(message)
  try {
    send(serializedMessage)
  } catch (e: Exception) {
    println("Some error occur: " + e.localizedMessage)
    return
  }
}

Here’s our simple server that going to get our message and send it back with some changes:

routing {
  webSocket("/hello") {
    try {
      for (frame in incoming) {
        frame as? Frame.Text ?: continue
        val deserializedMessage: WebSocketSession.Message =
          WebSocketSession.messagesFormat.decodeFromStream(frame.data.inputStream())
        val newMessageText = deserializedMessage.content + " - from Client"
        val serializedMessage = WebSocketSession.messagesFormat.encodeToString<WebSocketSession.Message>(
          WebSocketSession.SystemMessage(
            content = newMessageText,
            systemInfo = "Important"
          )
        )
        Connection(this).session.send(serializedMessage)
      }
    } catch (e: Exception) {
      println(e.localizedMessage)
    }
  }
}

The final part is to test it. We simply connect it to our already existing server:

fun main() {
  embeddedServer(Netty, port = 8080, host = "0.0.0.0") {
    configureUserRoutes()
    configureSerialization()
    configureSockets()
  }.start(wait = true)
}

And now run the client, for example, I’ve created this one:

suspend fun connectWebSocket() {
  client.webSocket(
    host = "0.0.0.0",
    port = 8080,
    path = "/hello"
  ) {
    launch { sendMessage(TextMessage("Good morning!")) }
    launch { receiveMessage() }
    delay(2000)
    launch { sendMessage(TextMessage("Hello!")) }
    launch { receiveMessage() }
    delay(2000)
    println("Connection closed. Goodbye!")
    client.close()
  }
}

runBlocking {
  WebSocketSession.connectWebSocket()
}

Here’s the results:

2023-12-01 15:46:26.104 [DefaultDispatcher-worker-4] TRACE io.ktor.websocket.WebSocket - Sending Frame TEXT (fin=true, buffer len = 41) from session io.ktor.websocket.DefaultWebSocketSessionImpl@2e8ab815
2023-12-01 15:46:26.110 [DefaultDispatcher-worker-6] TRACE io.ktor.websocket.WebSocket - WebSocketSession(StandaloneCoroutine{Active}@4ecfdc65) receiving frame Frame TEXT (fin=true, buffer len = 82)
Good morning! - from Client // Important
2023-12-01 15:46:28.094 [DefaultDispatcher-worker-6] TRACE io.ktor.websocket.WebSocket - Sending Frame TEXT (fin=true, buffer len = 34) from session io.ktor.websocket.DefaultWebSocketSessionImpl@2e8ab815
2023-12-01 15:46:28.097 [DefaultDispatcher-worker-3] TRACE io.ktor.websocket.WebSocket - WebSocketSession(StandaloneCoroutine{Active}@4ecfdc65) receiving frame Frame TEXT (fin=true, buffer len = 75)
Hello! - from Client // Important
Connection closed. Goodbye!

Summary

And that’s all for this article about kotlinx.serialization with Ktor.

If you would like to download the full source code, then you can find it in this GitHub repository.

Lastly, thank you for being here, and happy to hear your feedback in the comments section below!

The post How To Use kotlinx.serialization with Ktor and Kotlin? appeared first on Codersee blog- Kotlin on the backend.

If you haven’t seen my previous articles, then I highly encourage you to check them out:

• Secure REST API with Ktor and JWT Access Tokens
• Secure Ktor app with JWT refresh tokens. Refresh token flow.

Moreover, in this tutorial, we will build functionality based on the refresh token article, so I highly encourage you to fetch the code from this repo now. But don’t worry, if you are interested only in the RBAC part, then please navigate to the “Custom Ktor Authorization Plugin” paragraph.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

What Exactly Will We Do Today?

At the end of this tutorial, you will know precisely how to secure your Ktor REST API with role-based access control (RBAC).

But to be more specific, we will work with two endpoints:

The GET /api/user/{id} will be accessible for users with either ADMIN or USER roles. The second one, GET /api/user, will be accessible only for ADMIN users.

And how we will achieve that?

Well, we will implement a custom Ktor authorization plugin, which will be triggered on the AuthenticationChecked hook.

And I’ll show you how to do it the easy way, without unnecessary logic 🙂

What Is Role-Based Access Control (RBAC)?

Again, before we learn how to implement role-based access control (RBAC) in Ktor, let’s learn a bit about it.

Role-based access control (RBAC) or role-based security is nothing else than a way of restricting system access to authorized users.

To put it simply, we define a set of roles in our system, which reflects the needs of given permissions from our organization. An example of such a role can be a user, manager, admin, and many many more. And based on this role we allow, or deny access for a particular, authenticated user.

When dealing with JWT tokens in a REST API, such information can be first stored inside the token, so that later, we can easily read a claim and check whether a request should be served, or not.

Update User Class and Repo

With all of that said, let’s finally start the practice part.

As the first step, let’s navigate to the User class and insert a new field- role:

import java.util.UUID

data class User(
  val id: UUID,
  val username: String,
  val password: String,
  val role: String
)

For the sake of simplicity, let’s leave it as a String value, but depending on your needs, you may want to consider using an enum, or even a sealed class instead.

At this point, our code won’t compile, so let’s navigate to the UserRoute.kt and update the .toModel() extension function:

private fun UserRequest.toModel(): User =
  User(
    id = UUID.randomUUID(),
    username = this.username,
    password = this.password,
    role = "USER"
  )

As we can see, by default, all created users will have the USER role assigned.

Lastly, let’s navigate to the UserRepository and add some ADMIN user:

class UserRepository {

  private val users = mutableListOf(
    User(UUID.randomUUID(), "admin", "password", "ADMIN")
  )

  // the rest of the class
}

Add Role Claim to JWT Token

As the next step, let’s open up the JwtService and update these 3 functions:

fun createAccessToken(username: String, role: String): String =
  createJwtToken(username, role, 3_600_000)

fun createRefreshToken(username: String, role: String): String =
  createJwtToken(username, role, 86_400_000)

private fun createJwtToken(
  username: String,
  role: String, 
  expireIn: Int,
): String =
  JWT.create()
    .withAudience(audience)
    .withIssuer(issuer)
    .withClaim("username", username)
    .withClaim("role", role)
    .withExpiresAt(Date(System.currentTimeMillis() + expireIn))
    .sign(Algorithm.HMAC256(secret))

As I mentioned in the “theory” part- when dealing with JWT tokens, we can put information about the user’s role inside the token.

And that’s exactly what is happening here. From now on, every access and refresh token will contain an additional claim- the role– which will be populated with a role assigned to a user.

Update UserService

With that done, we must navigate to the UserService and update authenticate and refreshToken functions:

fun authenticate(loginRequest: LoginRequest): AuthResponse? {
  val username = loginRequest.username
  val foundUser: User? = userRepository.findByUsername(username)

  return if (foundUser != null && loginRequest.password == foundUser.password) {
    val accessToken = jwtService.createAccessToken(username, foundUser.role)
    val refreshToken = jwtService.createRefreshToken(username, foundUser.role)

    refreshTokenRepository.save(refreshToken, username)

    AuthResponse(
      accessToken = accessToken,
      refreshToken = refreshToken,
    )
  } else
    null
}

fun refreshToken(token: String): String? {
  val decodedRefreshToken = verifyRefreshToken(token)
  val persistedUsername = refreshTokenRepository.findUsernameByToken(token)

  return if (decodedRefreshToken != null && persistedUsername != null) {
    val foundUser: User? = userRepository.findByUsername(persistedUsername)
    val usernameFromRefreshToken: String? = decodedRefreshToken.getClaim("username").asString()

    if (foundUser != null && usernameFromRefreshToken == foundUser.username)
      jwtService.createAccessToken(persistedUsername, foundUser.role)
    else
      null
  } else
    null
}

From now on we must pass the user role to the JwtService when creating new tokens and that’s exactly what we updated here.

Custom Ktor Authorization Plugin

What Are Ktor Plugins?

Before we implement our custom one, let’s understand what exactly Ktor plugins are.

Basically, plugins in Ktor are a way to implement a common functionality that is out of the scope of the application logic. But what do we mean by that? Well, things like serialization, deserialization, compression, encoding, etc.

And when we take a look at the following diagram:

We will clearly see that plugins are everything that sits between request, application handler, and response. And yes, routing is a plugin too.

At this point, we can see that a custom plugin will be a great wait to achieve RBAC in our Ktor application. Moreover, we will use a new simplified API for creating custom plugins introduced in Ktor v2.0.0.

Implement Ktor RBAC Plugin

With all of that said, let’s navigate to the plugins package and create the RoleBasedAuthorization.kt and write the following:

import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*
import io.ktor.server.response.*

class PluginConfiguration {
  var roles: Set<String> = emptySet()
}

val RoleBasedAuthorizationPlugin = createRouteScopedPlugin(
  name = "RbacPlugin",
  createConfiguration = ::PluginConfiguration
) {
  val roles = pluginConfig.roles

  pluginConfig.apply {

    on(AuthenticationChecked) { call ->
      val tokenRole = getRoleFromToken(call)

      val authorized = roles.contains(tokenRole)

      if (!authorized) {
        println("User does not have any of the following roles: $roles")
        call.respond(HttpStatusCode.Forbidden)
      }
    }
  }
}

private fun getRoleFromToken(call: ApplicationCall): String? =
  call.principal<JWTPrincipal>()
    ?.payload
    ?.getClaim("role")
    ?.asString()

Firstly, we create the PluginConfiguration class with a roles field. This way, we will be able to configure later, which roles should be allowed for the given endpoint and which should be forbidden.

Later, we introduce our new, custom Ktor plugin using the createRouteScopedPlugin function. We must do that if we want to introduce a plugin that can be installed for a specific route.

Inside this function, we refer to pluginConfig and configure what exactly our custom authorization plugin must do. Firstly, we set the on handler that accepts a Hook as a parameter- in our case the AuthenticationChecked is a hook. As per the documentation:

AuthenticationChecked is executed after authentication credentials are checked.

Which simply means, that our plugin will be invoked after we authenticate the user successfully. With the old API, we would have to use the after Authentication.ChallengePhase.

Following, we extract the user role from the JWT role claim and if it is inside the Set with allowed roles, then we do nothing. Otherwise, we return 403 Forbidden.

Add RoleUtil

With that done, let’s navigate to the util package and introduce the authorized function inside the RouteUtil.kt:

import com.codersee.plugins.RoleBasedAuthorizationPlugin
import io.ktor.server.application.*
import io.ktor.server.routing.*

fun Route.authorized(
  vararg hasAnyRole: String,
  build: Route.() -> Unit
) {
  install(RoleBasedAuthorizationPlugin) { roles = hasAnyRole.toSet() }
  build()
}

To put it simply, we will use this function whenever we would like to authorize our request using role-based access control.

As a result, it will register our authorization plugin for a particular route.

Update User Routes

And with that said, let’s see it in action:

authenticate {
  authorized("ADMIN") {

    get {
      val users = userService.findAll()

      call.respond(
        message = users.map(User::toResponse)
      )
    }

  }
}

authenticate("another-auth") {
  authorized("ADMIN", "USER") {

    get("/{id}") {
      val id: String = call.parameters["id"]
        ?: return@get call.respond(HttpStatusCode.BadRequest)

      val foundUser = userService.findById(id)
        ?: return@get call.respond(HttpStatusCode.NotFound)

      if (foundUser.username != extractPrincipalUsername(call))
        return@get call.respond(HttpStatusCode.NotFound)

      call.respond(
        message = foundUser.toResponse()
      )
    }
  }

As we can see, from now on we can simply use the authorized whenever we want to limit endpoint accessibility to particular roles.

Of course, we must remember that this can be done only when the user is authenticated, because otherwise, we won’t be able to read the role claim.

Ktor RBAC summary

And that’s all for this article on how to implement role-based access control (RBAC) in Ktor.

I hope this article (and a series) helped you to learn how easily we can set up different things related to security in Ktor. If you haven’t seen previous materials yet, then you can do that right here:

• Secure REST API with Ktor and JWT Access Tokens
• Secure Ktor app with JWT refresh tokens. Refresh token flow.

As always, you can find a source code in this GitHub repository and let me know your thoughts in the comments section below 🙂

The post Secure REST API with Ktor – Role-based access control (RBAC) appeared first on Codersee blog- Kotlin on the backend.

To not duplicate ourselves, we will use the project implemented in the previous blog post, in which we learned how to implement a secure REST API with Ktor and authenticate with JWT access tokens. So if you haven’t read that article yet, I highly encourage you to do it now. Nevertheless, if you are interested more in the refresh token part, you can find a link to the GitHub repository and simply clone the project.

Without any further ado, let’s get to work 🙂

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

A Tiny Bit Of Theory

If you’re following me for a longer period, you know that I focus on the practical side of different problems.

Nevertheless, I owe you a bit of explanation before we learn how to secure our Ktor app with JWT refresh token flow. So, in the following paragraphs, I will shortly describe:

• the difference between access tokens and refresh tokens,
• what is a refresh token flow,
• and advantages of such a flow.

Of course, if you feel that’s not necessary in your case, then feel free to skip to the Implement RefreshTokenRepository section 😉

Access Tokens vs Refresh Tokens

Let’s start everything by distinguishing these two.

First of all, they both play distinct roles in token-based authentication systems.

An access token is a short-lived credential that is issued to a client after a successful authentication. Its purpose is to grant the client permission to access protected resources on behalf of the user. And by the client, we mean here a web app, a mobile app, or any other integration working with our REST API.

They are designed to have a limited lifespan to enhance security, reducing the risk associated with compromised tokens.

Refresh tokens, on the other hand, are long-lived credentials that are used to obtain new access tokens without requiring the user to re-authenticate.

While access tokens are meant for short-term authorization, refresh tokens provide a mechanism for obtaining fresh access tokens and extending the user’s session securely.

Refresh Token Flow

To put it simply, when a client authenticates successfully, it receives two tokens: an access token, and a refresh token.

The access token will be used to query our API. If it is compromised, the bad actor will have a limited time to perform unwanted actions on behalf of the user (thanks to its short-lived nature).

The refresh token, with a longer expiration time, will allow the client to get a new access token whenever it expires. This way, the user does not need to specify credentials (like username, and password for instance) every time an access token expires.

With this flow, we can strike a balance between usability and security. We improve user experience and maintain protection against unauthorized access.

Pros vs Cons

As with every solution, refresh token flow has both pros and cons.

When it comes to the advantages, we already covered the first two- the shorter lifespan of access tokens limits the potential impact of a token compromise. Additionally, a long-living refresh token means a better user experience– a longer time between asking the user for his credentials. Lastly, this flow gives us more granular control over token management, for example, we can revoke refresh tokens selectively.

When it comes to the disadvantages, we could call them additional complexity. Not only we must carefully implement on the backend to prevent any vulnerabilities, but also, the storage and transmission of refresh tokens need to be handled securely to prevent unauthorized access.

Lastly, should we always use refresh token flow in our applications?

The answer is- as always- it depends. When dealing with security for our app we should spend some time investigating in depth all options on the table. Such an analysis would be way too much for the article about implementing a Ktor JWT refresh token flow 😉

Implement RefreshTokenRepository

With all of that said, we can finally start the practice part.

As the first step, let’s navigate to the repository package in our Ktor project and add the RefreshTokenRepository class:

class RefreshTokenRepository {

  private val tokens = mutableMapOf<String, String>()

  fun findUsernameByToken(token: String): String? =
    tokens[token]

  fun save(token: String, username: String) {
    tokens[token] = username
  }

}

Again, in a real-life scenario, this would be the class responsible for communicating to the data source, like a relational database, MongoDB, or any other source used in the project. To keep our tutorial simple and focused on the Ktor/JWT combination, we will use a mutable map storing a combination of tokens with usernames in memory.

As we can see, this class exposes two functions. One is for persisting the data in our map, and the second one is to retrieve usernames based on the JWT refresh token value.

Update JwtService

Nextly, let’s open up the JwtService class and update it a bit:

import com.auth0.jwt.JWT
import com.auth0.jwt.JWTVerifier
import com.auth0.jwt.algorithms.Algorithm
import com.codersee.model.User
import com.codersee.repository.UserRepository
import io.ktor.server.application.*
import io.ktor.server.auth.jwt.*
import java.util.*

class JwtService(
  private val application: Application,
  private val userRepository: UserRepository,
) {

  private val secret = getConfigProperty("jwt.secret")
  private val issuer = getConfigProperty("jwt.issuer")
  private val audience = getConfigProperty("jwt.audience")

  val realm = getConfigProperty("jwt.realm")

  val jwtVerifier: JWTVerifier =
    JWT
      .require(Algorithm.HMAC256(secret))
      .withAudience(audience)
      .withIssuer(issuer)
      .build()

  fun createAccessToken(username: String): String =
    createJwtToken(username, 3_600_000)

  fun createRefreshToken(username: String): String =
    createJwtToken(username, 86_400_000)

  private fun createJwtToken(username: String, expireIn: Int): String =
    JWT.create()
      .withAudience(audience)
      .withIssuer(issuer)
      .withClaim("username", username)
      .withExpiresAt(Date(System.currentTimeMillis() + expireIn))
      .sign(Algorithm.HMAC256(secret))


  fun customValidator(
    credential: JWTCredential,
  ): JWTPrincipal? {
    val username: String? = extractUsername(credential)
    val foundUser: User? = username?.let(userRepository::findByUsername)

    return foundUser?.let {
      if (audienceMatches(credential))
        JWTPrincipal(credential.payload)
      else
        null
    }
  }

  private fun audienceMatches(
    credential: JWTCredential,
  ): Boolean =
    credential.payload.audience.contains(audience)

  fun audienceMatches(
    audience: String
  ): Boolean =
    this.audience == audience

  private fun getConfigProperty(path: String) =
    application.environment.config.property(path).getString()

  private fun extractUsername(credential: JWTCredential): String? =
    credential.payload.getClaim("username").asString()
}

First of all, we replaced the UserService dependency from the constructor with the UserRepository. This way, we would avoid a circular dependency between this class and UserService later.

Then, we extracted the code responsible for generating JWT tokens into a separate function- createJwtToken– which will be called by the createAccessToken, and createRefreshToken. Please note that these two functions declare different expiration times for both token types- 1 hour for the access token and 24 for the refresh token.

But what expiration time should we set in a real-life? Well, again, it depends 🙂 And we must consider both security concerns, as well as the storage. Yes, the longer the expiration time, the bigger the amount of refresh tokens stored in our database.

Lastly, we added the audienceMatches function, which we will use later in the code.

Update Routing Layer

With all of that done, let’s navigate to the routing package and make the necessary changes too.

Add Request/Response Classes

As the first step, let’s add a class responsible for mapping refresh token call JSON payload:

import kotlinx.serialization.Serializable

@Serializable
data class RefreshTokenRequest(
  val token: String,
)

Following, let’s implement a class, which will serialize the authentication response:

import kotlinx.serialization.Serializable

@Serializable
data class AuthResponse(
  val accessToken: String,
  val refreshToken: String,
)

And finally, the RefreshTokenResponse:

import kotlinx.serialization.Serializable

@Serializable
data class RefreshTokenResponse(
  val token: String,
)

Update Routing.kt

As the next step, let’s update the Routing.kt class:

import com.codersee.service.UserService
import io.ktor.server.application.*
import io.ktor.server.routing.*

fun Application.configureRouting(
  userService: UserService
) {
  routing {

    route("/api/auth") {
      authRoute(userService)
    }

    route("/api/user") {
      userRoute(userService)
    }

  }
}

As we can see, we don’t inject the JwtService anymore. Instead, we invoke the authRoute with UserService instance instead.

Edit AuthRoute.kt

import com.codersee.routing.request.LoginRequest
import com.codersee.routing.request.RefreshTokenRequest
import com.codersee.routing.response.AuthResponse
import com.codersee.routing.response.RefreshTokenResponse
import com.codersee.service.UserService
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Route.authRoute(userService: UserService) {

  post {
    val loginRequest = call.receive<LoginRequest>()

    val authResponse: AuthResponse? = userService.authenticate(loginRequest)

    authResponse?.let {
      call.respond(authResponse)
    } ?: call.respond(
      message = HttpStatusCode.Unauthorized
    )
  }

  post("/refresh") {
    val request = call.receive<RefreshTokenRequest>()

    val newAccessToken = userService.refreshToken(token = request.token)

    newAccessToken?.let {
      call.respond(
        RefreshTokenResponse(it)
      )
    } ?: call.respond(
      message = HttpStatusCode.Unauthorized
    )
  }

}

So, instead of dealing with JwtService, we are going to invoke the UserService functions instead.

In the first handler for POST /api/auth calls, we invoke the authenticate method and if we receive an AuthResponse, then we will simply return that to the API client with 200 OK status. Otherwise, we will return 401 Unauthorized.

Additionally, we add a new handler for POST /api/auth/refresh calls. Inside it, we read the JSON payload and create an instance of RefreshTokenRequest. Then, we invoke the refreshToken method from UserService (which we are going to implement in a moment). And just like previously, if the service returns a non-null object, then we respond with 200 OK and with 401 Unauthorized if that’s not the case.

Update UserService

As the last thing in our Ktor with the JWT refresh token tutorial, we must update the UserService:

import com.auth0.jwt.interfaces.DecodedJWT
import com.codersee.model.User
import com.codersee.repository.RefreshTokenRepository
import com.codersee.repository.UserRepository
import com.codersee.routing.request.LoginRequest
import com.codersee.routing.response.AuthResponse
import java.util.*

class UserService(
  private val userRepository: UserRepository,
  private val jwtService: JwtService,
  private val refreshTokenRepository: RefreshTokenRepository
) {

  fun findAll(): List<User> =
    userRepository.findAll()

  fun findById(id: String): User? =
    userRepository.findById(
      id = UUID.fromString(id)
    )

  fun findByUsername(username: String): User? =
    userRepository.findByUsername(username)

  fun save(user: User): User? {
    val foundUser = userRepository.findByUsername(user.username)

    return if (foundUser == null) {
      userRepository.save(user)
      user
    } else null
  }

  fun authenticate(loginRequest: LoginRequest): AuthResponse? {
    val username = loginRequest.username
    val foundUser: User? = userRepository.findByUsername(username)

    return if (foundUser != null && loginRequest.password == foundUser.password) {
      val accessToken = jwtService.createAccessToken(username)
      val refreshToken = jwtService.createRefreshToken(username)

      refreshTokenRepository.save(refreshToken, username)

      AuthResponse(
        accessToken = accessToken,
        refreshToken = refreshToken,
      )
    } else
      null
  }

  fun refreshToken(token: String): String? {
    val decodedRefreshToken = verifyRefreshToken(token)
    val persistedUsername = refreshTokenRepository.findUsernameByToken(token)

    return if (decodedRefreshToken != null && persistedUsername != null) {
      val foundUser: User? = userRepository.findByUsername(persistedUsername)
      val usernameFromRefreshToken: String? = decodedRefreshToken.getClaim("username").asString()

      if (foundUser != null && usernameFromRefreshToken == foundUser.username)
        jwtService.createAccessToken(persistedUsername)
      else
        null
    } else
      null
  }

  private fun verifyRefreshToken(token: String): DecodedJWT? {
    val decodedJwt: DecodedJWT? = getDecodedJwt(token)

    return decodedJwt?.let {
      val audienceMatches = jwtService.audienceMatches(it.audience.first())

      if (audienceMatches)
        decodedJwt
      else
        null
    }
  }

  private fun getDecodedJwt(token: String): DecodedJWT? =
    try {
      jwtService.jwtVerifier.verify(token)
    } catch (ex: Exception) {
      null
    }
}

And let’s see the most important changes here.

Firstly, we add the authenticate function:

fun authenticate(loginRequest: LoginRequest): AuthResponse? {
  val username = loginRequest.username
  val foundUser: User? = userRepository.findByUsername(username)

  return if (foundUser != null && loginRequest.password == foundUser.password) {
    val accessToken = jwtService.createAccessToken(username)
    val refreshToken = jwtService.createRefreshToken(username)

    refreshTokenRepository.save(refreshToken, username)

    AuthResponse(
      accessToken = accessToken,
      refreshToken = refreshToken,
    )
  } else
    null
}

This one is simply responsible for fetching a user from our repository using the passed username.

If we find it successfully, we check if the password matches (again, it’s just a dummy plain text comparison and you want to learn more about password checks in real-life scenarios). And if that’s the case, then we simply return the access and refresh tokens to the user and persist the refresh token in our “database”.

Nextly, we have a refresh token flow function:

fun refreshToken(token: String): String? {
  val decodedRefreshToken = verifyRefreshToken(token)
  val persistedUsername = refreshTokenRepository.findUsernameByToken(token)

  return if (decodedRefreshToken != null && persistedUsername != null) {
    val foundUser: User? = userRepository.findByUsername(persistedUsername)
    val usernameFromRefreshToken: String? = decodedRefreshToken.getClaim("username").asString()

    if (foundUser != null && usernameFromRefreshToken == foundUser.username)
      jwtService.createAccessToken(persistedUsername)
    else
      null
  } else
    null
}

When it comes to refreshing a token, we check if there is any persisted username found by the token value. If it is, then we fetch the user by the given username (this way, we won’t refresh a token for user that does not exist anymore).

And at this point, we can rerun our application and verify if our logic works, as expected. Again, if you’d like to get a ready-to-go Postman collection, then please let me know in the comments section.

Ktor With JWT Refresh Token Summary

And basically, that’s all for this, second tutorial in a series related to Ktor security, in which we learned how to create a Ktor application with JWT refresh token flow.

As always, you can find the whole source code in my GitHub repository.

Thank you for being here and please do not forget to share it with other people on your social media (it will help me a lot) and check other posts from the series:

• Secure REST API with Ktor and JWT Access Tokens,
• and how to add a role-based access control (RBAC) to the project.

The post Secure Ktor app with JWT refresh tokens. Refresh token flow. appeared first on Codersee blog- Kotlin on the backend.

To be even more specific, in this tutorial I will teach you:

• how to implement a simple REST API,
• what are JSON Web Tokens and what does the authentication mean,
• how to generate and validate JWT access tokens, and authenticate users,
• and how to read data using the JWTPrincipal.

In the upcoming articles, we will continue the topic and learn additionally:

• how to implement a refresh token flow with Ktor,
• and how to add a role-based access control (RBAC) to the project.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

What Is Authentication?

But before we start implementing our Ktor app with JWT tokens, let me quickly explain what exactly authentication is.

In essence, it is the process of verifying the identity of a user, system, or device to ensure that they are who they claim to be.

It is like having a secret code to enter a club. Let’s imagine we want to get into a cool party, and at the entrance, there’s a bouncer checking everyone’s membership. To prove we belong, we provide a special password. If the password matches what’s on the list, we’re in!

In the digital world, it’s the same idea – we need to confirm our identity with a unique key (like a password or JWT token) to access our email, bank account, or, like in our case, any resource through the exposed REST API.

Of course, authentication is not a synonym for authorization (but we will get back to that in the upcoming post).

JWT Tokens Explained

As the last thing before we head to the practice, let’s learn a bit about the JWT tokens.

JWTs, also known as JSON Web Tokens, are nothing else than one of plenty of existing ways to authenticate users.

Just like with our previous example- in real life, we can use our ID, passport, or in other cases, some secret word.

Here, the JWT is like a digital secret handshake on the internet. When sign in using our username and password, the server gives us a special JWT, and later, we can use it to access a REST API. This way, we don’t need to specify such vulnerable data every time we want to make a request.

What are the other advantages? Well, they are safe and compact, and allow us to hold information.

JWTs consist of three parts separated by dots: header.payload.signature:

The encoded value can be easily decoded and JWT token values can be read.

The header typically consists of two parts: the type of the token (missing above), and the signing algorithm being used (HMAC SHA512).

The second part of the token is the payload, which contains the claims. Claims, Claims are statements about an entity (typically, the user) and additional data.

Lastly, the signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way.

Set Up New Ktor Project

With all of that said, let’s navigate to the Ktor Project Generator and start by specifying the necessary details:

At this stage, we must specify the basic things, like the Ktor version, engine, etc.

Nextly, let’s click the “Add plugins” button and configure the following plugins (aka dependencies):

As we can see, in order to expose a REST API and secure it with JWT in Ktor, we will need the following:

• Authentication,
• Authentication JWT,
• Content Negotiation,
• kotlinx.serialization,
• and Routing.

With that done, let’s generate the project, download the ZIP file, extract it, and import it to the IntelliJ IDEA.

When we open up the project, we should see that there are some plugins already configured inside the plugins package and Application.kt file.

Let’s delete files inside the plugins and clean up the Application.kt to be on the same page:

import io.ktor.server.application.*

fun main(args: Array<String>) {
  io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {
}

Expose Users API

As the next step, let’s expose the API responsible for user management.

Add User Model

Firstly, let’s create the model package and implement the User.kt class:

import java.util.UUID

data class User(
  val id: UUID,
  val username: String,
  val password: String
)

As can be seen, it’s just a simple class with the id, username, and password fields.

Create UserRepository

Secondly, we must add a class responsible for user storage and retrieval.

To do so, let’s add the repository package and put the UserRepository inside it:

import com.codersee.model.User
import java.util.*

class UserRepository {

  private val users = mutableListOf<User>()

  fun findAll(): List<User> =
    users

  fun findById(id: UUID): User? =
    users.firstOrNull { it.id == id }

  fun findByUsername(username: String): User? =
    users.firstOrNull { it.username == username }

  fun save(user: User): Boolean =
    users.add(user)
}

Normally, we would put a code responsible for “talking” to the database right here.

In our case, to not lose focus from the clue of this article- authentication in Ktor and JWT- we introduce a dummy repository, which uses the mutable list to store users in memory.

Note: in our dummy repository, we store user password in a plain text.

Nevertheless, in real-life scenarios we should always encrypt it before persisting. To learn a bit more about different encryption algorithms, you can check out my other post in which I explain PBKDF2 hashing.

Implement UserService

With that done, let’s introduce a service layer in our project.

So, similarly, let’s add the service package and the UserService class:

import com.codersee.model.User
import com.codersee.repository.UserRepository
import java.util.*

class UserService(
  private val userRepository: UserRepository
) {

  fun findAll(): List<User> =
    userRepository.findAll()

  fun findById(id: String): User? =
    userRepository.findById(
      id = UUID.fromString(id)
    )

  fun findByUsername(username: String): User? =
    userRepository.findByUsername(username)

  fun save(user: User): User? {
    val foundUser = userRepository.findByUsername(user.username)

    return if (foundUser == null) {
      userRepository.save(user)
      user
    } else null
  }
}

This time, we expose 4 functions, which we will utilize later when handling requests and working with JWT tokens.

Add Request and Response Classes

Before we expose our REST endpoint, let’s take care of the request and response classes.

Let’s start by creating the routing.request package and implementing the UserRequest:

import kotlinx.serialization.Serializable

@Serializable
data class UserRequest(
  val username: String,
  val password: String,
)

As we can see, we must annotate objects that we want to serialize or deserialize using the @Serializable when working with kotlinx.serialization library.

As a result, the serialization plugin will automatically generate the implementation of KSerializer.

Similarly, let’s add the routing.response package and the UserResponse:

import kotlinx.serialization.Serializable
import java.util.*

@Serializable
data class UserResponse(
  val id: UUID,
  val username: String,
)

This one seems pretty similar, but unfortunately, we must do one more thing here.

Custom UUID KSerializer

If we would try to use this class as it is, we would end up with the following error:

Serializer has not been found for type ‘UUID’. To use context serializer as fallback, explicitly annotate type or property with @Contextual.

And to fix this issue, we must implement our own UUID serializer.

So as the first step, let’s introduce the util package and add the UUIDSerializer object:

import kotlinx.serialization.KSerializer
import kotlinx.serialization.descriptors.PrimitiveKind
import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
import kotlinx.serialization.descriptors.SerialDescriptor
import kotlinx.serialization.encoding.Decoder
import kotlinx.serialization.encoding.Encoder
import java.util.*

object UUIDSerializer : KSerializer<UUID> {

  override val descriptor: SerialDescriptor
    get() = PrimitiveSerialDescriptor("UUID", PrimitiveKind.STRING)

  override fun deserialize(decoder: Decoder): UUID =
    UUID.fromString(decoder.decodeString())

  override fun serialize(encoder: Encoder, value: UUID) =
    encoder.encodeString(value.toString())
}

Following, let’s instruct the plugin to use our implementation whenever it wants to serialize the id field:

import com.codersee.util.UUIDSerializer
import kotlinx.serialization.Serializable
import java.util.*

@Serializable
data class UserResponse(
  @Serializable(with = UUIDSerializer::class)
  val id: UUID,
  val username: String,
)

Register Serialization Plugin

When working with Ktor, we must explicitly specify the plugins we use. There is no component scan based on the dependencies which you may know from Spring Boot 🙂

So as the next step, let’s add the Seriaization.kt to the plugins package:

import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*

fun Application.configureSerialization() {
  install(ContentNegotiation) {
    json()
  }
}

The ContentNegotiation plugin has two tasks:

• it negotiates the media types between the client and server,
• and serializes/deserializes the content in a specific format.

In our case, we can clearly see that we will be using the JSON format.

Note: other formats, like XML, CBOR, and ProtoBuf are supported, too.

Lastly, we must make use of our extension function inside the Application.kt file:

import com.codersee.plugins.configureSerialization
import io.ktor.server.application.*

fun main(args: Array<String>) {
  io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {
  configureSerialization()
}

Add User Route

With all of that being done, we can finally expose endpoints for user management.

As the first step, let’s implement the Routing.kt class inside the routing package:

import com.codersee.service.UserService
import io.ktor.server.application.*
import io.ktor.server.routing.*

fun Application.configureRouting(
  userService: UserService
) {
  routing {

    route("/api/user") {
      userRoute(userService)
    }

  }
}

This way, we instruct Ktor that whenever a request is made to the /api/user**, it should look for a handler inside the userRoute (which we will add in a moment).

Following, let’s get back to the Application.kt and register our routing:

import com.codersee.plugins.configureSerialization
import com.codersee.repository.UserRepository
import com.codersee.routing.configureRouting
import com.codersee.service.UserService
import io.ktor.server.application.*

fun main(args: Array<String>) {
  io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {
  val userRepository = UserRepository()
  val userService = UserService(userRepository)

  configureSerialization()
  configureRouting(userService)
}

Nextly, let’s add the UserRoute.kt inside the routing package:

import com.codersee.model.User
import com.codersee.routing.request.UserRequest
import com.codersee.routing.response.UserResponse
import com.codersee.service.UserService
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import java.util.*

fun Route.userRoute(userService: UserService) {

  post {
    val userRequest = call.receive<UserRequest>()

    val createdUser = userService.save(
      user = userRequest.toModel()
    ) ?: return@post call.respond(HttpStatusCode.BadRequest)

    call.response.header(
      name = "id",
      value = createdUser.id.toString()
    )
    call.respond(
      message = HttpStatusCode.Created
    )
  }

  get {
    val users = userService.findAll()

    call.respond(
      message = users.map(User::toResponse)
    )
  }

  get("/{id}") {
    val id: String = call.parameters["id"]
      ?: return@get call.respond(HttpStatusCode.BadRequest)

    val foundUser = userService.findById(id)
      ?: return@get call.respond(HttpStatusCode.NotFound)

    call.respond(
      message = foundUser.toResponse()
    )
  }
}

private fun UserRequest.toModel(): User =
  User(
    id = UUID.randomUUID(),
    username = this.username,
    password = this.password
  )

private fun User.toResponse(): UserResponse =
  UserResponse(
    id = this.id,
    username = this.username,
  )

And to be on the same page, let’s rephrase what is going on here:

import com.codersee.model.User
import com.codersee.routing.request.UserRequest
import com.codersee.routing.response.UserResponse
import com.codersee.service.UserService
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import java.util.*

fun Route.userRoute(userService: UserService) {

  post {
    val userRequest = call.receive<UserRequest>()

    val createdUser = userService.save(
      user = userRequest.toModel()
    ) ?: return@post call.respond(HttpStatusCode.BadRequest)

    call.response.header(
      name = "id",
      value = createdUser.id.toString()
    )
    call.respond(
      message = HttpStatusCode.Created
    )
  }

}

Firstly, we inject the instance of UserService, which we will use to save and retrieve users.

Nextly, we specify a handler for POST requests.

Inside this handler, we get the JSON payload sent by the API consumer as an instance of UserRequest with the call.receive<T>() function. Then, we invoke the save function and pass the instance of the User class, which we obtain using the toModel() extension function. If the save returns a null value, we return 400 Bad Request with the call.respond() function.

On the other hand, if the user was saved successfully, we respond with a 201 Created status and pass its identifier as the id header value with call.response.header() function.

Then, we have another handler responsible for GET /api/user requests:

get {
  val users = userService.findAll()

  call.respond(
    message = users.map(User::toResponse)
  )
}

It is responsible for fetching all users and returning them after mapping with toResponse() extension functions.

Lastly, we have the handler answering to the GET /api/user/{id} requests:

get("/{id}") {
  val id: String = call.parameters["id"]
    ?: return@get call.respond(HttpStatusCode.BadRequest)

  val foundUser = userService.findById(id)
    ?: return@get call.respond(HttpStatusCode.NotFound)

  call.respond(
    message = foundUser.toResponse()
  )
}

This time, we read the path variable id using the call.paramaters. If is not present, we return a 400 Bad Request response.

Following, we try to find a user by ID and if we fail, then we simply return the 404 Not Found.

Ktor With JWT

Excellent! At this point, we have a working API, so it’s finally time to learn a bit more about how to secure it, and how to generate JWT tokens in our Ktor application so that we can use them later to access these endpoints.

Update Config File

As the first step, let’s navigate to the application.conf file.

Among other settings, we should see the following jwt:

jwt {
    domain = "https://jwt-provider-domain/"
    audience = "jwt-audience"
    realm = "ktor sample app"
}

Let’s slightly modify it:

jwt {
    audience = "my-audience"
    issuer = "http://localhost/"
    realm = "My realm"
    secret = ${SECRET}
}

Without going into too much detail, these values (except for the secret) will be claims in our JWT tokens:

• audience– which describes the recipient of the token,
• issuer– which is the entity that issues the token,
• realm– which is an optional parameter providing additional context or scope,
• secret– which is a secret key used for token signing and verification.

Please note that the secret value IS NOT hardcoded (and should never be). We will source it from the environment variable called SECRET.

Implement JwtService

With that done, we can navigate to the service package and add the JwtService:

import com.auth0.jwt.JWT
import com.auth0.jwt.JWTVerifier
import com.auth0.jwt.algorithms.Algorithm
import com.codersee.model.User
import io.ktor.server.application.*
import io.ktor.server.auth.jwt.*
import java.util.*

class JwtService(
  private val application: Application,
  private val userService: UserService,
) {

  private val secret = getConfigProperty("jwt.secret")
  private val issuer = getConfigProperty("jwt.issuer")
  private val audience = getConfigProperty("jwt.audience")

  val realm = getConfigProperty("jwt.realm")

  val jwtVerifier: JWTVerifier =
    JWT
      .require(Algorithm.HMAC256(secret))
      .withAudience(audience)
      .withIssuer(issuer)
      .build()

  fun createJwtToken(loginRequest: LoginRequest): String? {
    val foundUser: User? = userService.findByUsername(loginRequest.username)

    return if (foundUser != null && loginRequest.password == foundUser.password)
      JWT.create()
        .withAudience(audience)
        .withIssuer(issuer)
        .withClaim("username", loginRequest.username)
        .withExpiresAt(Date(System.currentTimeMillis() + 3_600_000))
        .sign(Algorithm.HMAC256(secret))
    else
      null
  }

  fun customValidator(
    credential: JWTCredential,
  ): JWTPrincipal? {
    val username: String? = extractUsername(credential)
    val foundUser: User? = username?.let(userService::findByUsername)

    return foundUser?.let {
      if (audienceMatches(credential))
        JWTPrincipal(credential.payload)
      else
        null
    }
  }

  private fun audienceMatches(
    credential: JWTCredential,
  ): Boolean =
    credential.payload.audience.contains(audience)

  private fun getConfigProperty(path: String) =
    application.environment.config.property(path).getString()

  private fun extractUsername(credential: JWTCredential): String? =
    credential.payload.getClaim("username").asString()
}

Again, let’s break it down into smaller chunks:

import com.auth0.jwt.JWT
import com.auth0.jwt.JWTVerifier
import com.auth0.jwt.algorithms.Algorithm
import com.codersee.model.User
import io.ktor.server.application.*
import io.ktor.server.auth.jwt.*
import java.util.*

class JwtService(
  private val application: Application,
  private val userService: UserService,
) {

  private val secret = getConfigProperty("jwt.secret")
  private val issuer = getConfigProperty("jwt.issuer")
  private val audience = getConfigProperty("jwt.audience")

  val realm = getConfigProperty("jwt.realm")

  val jwtVerifier: JWTVerifier =
    JWT
      .require(Algorithm.HMAC256(secret))
      .withAudience(audience)
      .withIssuer(issuer)
      .build()

  private fun getConfigProperty(path: String) =
    application.environment.config.property(path).getString()
}

Firstly, we inject the instance of Application and UserService classes.

Following we read the configuration properties we set in the previous step. 3 of them can be private, but the realm will be later used in another class to configure security.

After that, we must create an instance of the JwtVerifier and configure it. In simple words, this class holds the verify method which will later verify that a given token has not only a proper JWT format but also its signature matches.

And this is why we specify which algorithm, audience, and issuer a valid token must have.

With all of that done, we introduce the createJwtToken function:

fun createJwtToken(loginRequest: LoginRequest): String? {
  val foundUser: User? = userService.findByUsername(loginRequest.username)

  return if (foundUser != null && loginRequest.password == foundUser.password)
    JWT.create()
      .withAudience(audience)
      .withIssuer(issuer)
      .withClaim("username", loginRequest.username)
      .withExpiresAt(Date(System.currentTimeMillis() + 3_600_000))
      .sign(Algorithm.HMAC256(secret))
  else
    null
}

This one takes the username as an argument and tries to find a user with it.

If we succeed and the password matches, then we produce a new JWT access token with the appropriate audience, issuer, and username, expiring in 60 minutes and signed with the HMAC-SHA256 algorithm (with our secret key).

Lastly, we add the customValidator function, which we will later use to add an additional validation:

fun customValidator(
  credential: JWTCredential,
): JWTPrincipal? {
  val username: String? = extractUsername(credential)
  val foundUser: User? = username?.let(userService::findByUsername)

  return foundUser?.let {
    if (audienceMatches(credential))
      JWTPrincipal(credential.payload)
    else
      null
  }
}

private fun audienceMatches(
  credential: JWTCredential,
): Boolean =
  credential.payload.audience.contains(audience)

private fun extractUsername(credential: JWTCredential): String? =
  credential.payload.getClaim("username").asString()

As the first thing, we extract the username from the JWT token and we try to find a user by this value.

If we succeed, then we check if the audience from the token matches the audience set in our Ktor project. If that’s true, then we instantiate the JWTPrincipal, which we will use later to obtain the information.

Install Authentication Plugin

At this point, we have the JWT service ready, so it’s time to install the Authentication plugin.

To do so, let’s add the Security plugin inside the plugins package:

import com.codersee.service.JwtService
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*

fun Application.configureSecurity(
  jwtService: JwtService
) {
  authentication {
    jwt {
      realm = jwtService.realm
      verifier(jwtService.jwtVerifier)

      validate { credential ->
        jwtService.customValidator(credential, jwtService)
      }
    }
  }
}

But what exactly is going on here?

The above code installs the Authentication plugin (authentication) with JWT Authentication provider (jwt).

Additionally, we must specify the realm, verifier, and the custom validate function that we implemented previously.

And what if we would like to have multiple providers in our project?

Well, we can do that easily by simply specifying a new one with a name:

import com.codersee.service.JwtService
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*

fun Application.configureSecurity(
  jwtService: JwtService
) {
  authentication {
    jwt {
      realm = jwtService.realm
      verifier(jwtService.jwtVerifier)

      validate { credential ->
        jwtService.customValidator(credential, jwtService)
      }
    }

    jwt("another-auth") {
      realm = jwtService.realm
      verifier(jwtService.jwtVerifier)

      validate { credential ->
        jwtService.customValidator(credential, jwtService)
      }
    }
  }
}

Later, we will see how to make use of these JWT auth providers, but for now, let’s navigate to the Application.kt file and make use of our new config:

import com.codersee.plugins.configureSecurity
import com.codersee.plugins.configureSerialization
import com.codersee.repository.UserRepository
import com.codersee.routing.configureRouting
import com.codersee.service.JwtService
import com.codersee.service.UserService
import io.ktor.server.application.*

fun main(args: Array<String>) {
  io.ktor.server.netty.EngineMain.main(args)
}

fun Application.module() {
  val userRepository = UserRepository()
  val userService = UserService(userRepository)
  val jwtService = JwtService(this, userService)

  configureSerialization()
  configureSecurity(jwtService)
  configureRouting(jwtService, userService)
}

Expose Login Endpoint

Perfect! At this point we have everything we need to expose a new endpoint- POST /api/auth– which we will use to get JWT access tokens for our Ktor app based on the passed username and password.

So as the first step, let’s go to the Routing file, inject the JwtService and prepare a new route:

import com.codersee.service.JwtService
import com.codersee.service.UserService
import io.ktor.server.application.*
import io.ktor.server.routing.*

fun Application.configureRouting(
  jwtService: JwtService,
  userService: UserService
) {
  routing {

    route("/api/auth") {
      authRoute(jwtService)
    }

    route("/api/user") {
      userRoute(userService)
    }

  }
}

Nextly, let’s implement the LoginRequest inside the routing.request:

import kotlinx.serialization.Serializable

@Serializable
data class LoginRequest(
  val username: String,
  val password: String,
)

No traps here this time, so let’s create the AuthRoute.kt file:

import com.codersee.routing.request.LoginRequest
import com.codersee.service.JwtService
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Route.authRoute(jwtService: JwtService) {

  post {
    val user = call.receive<LoginRequest>()

    val token: String? = jwtService.createJwtToken(user.username)

    token?.let {
      call.respond(hashMapOf("token" to token))
    } ?: call.respond(
      message = HttpStatusCode.Unauthorized
    )
  }

}

This time, we read the request payload to the LoginRequest instance and we try to create a new JWT access token based on the username.

If we succeed (meaning a user with the following username was found and the password matches), then we return a fresh JWT access token. Otherwise, we simply return 401 Unauthorized to the API consumer.

At this point, we can test the app, for example by using curl (and if you would like to get a full Postman collection with automated token handling, then please leave a comment for this article).

Let’s start by creating a new user:

curl --location --request POST 'http://localhost:8080/api/user' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "user", 
    "password": "password"
}'

As a response, we should get 201 Created with the id in the response header.

Following, let’s try to get a JWT access token:

curl --location --request POST 'http://localhost:8080/api/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "user", 
    "password": "password"
}'

// Response:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteS1hdWRpZW5jZSIsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3QvIiwidXNlcm5hbWUiOiJ1c2VyIiwiZXhwIjoxNzAwMTU2Mzg4fQ.DG8SsNrQI5-VqrZeZMFL4IRuVSLeo9Zs9dEifti9nvQ"
}

Excellent! So far so good.

You can even take this token and check it out using the jwt.io page 🙂

Secure User Endpoint

Finally, let’s secure user API endpoints:

fun Route.userRoute(userService: UserService) {

  post {
    val userRequest = call.receive<UserRequest>()

    val createdUser = userService.save(
      user = userRequest.toModel()
    ) ?: return@post call.respond(HttpStatusCode.BadRequest)

    call.response.header(
      name = "id",
      value = createdUser.id.toString()
    )
    call.respond(
      message = HttpStatusCode.Created
    )
  }

  authenticate {
    get {
      val users = userService.findAll()

      call.respond(
        message = users.map(User::toResponse)
      )
    }
  }

  authenticate("another-auth") {
    get("/{id}") {
      val id: String = call.parameters["id"]
        ?: return@get call.respond(HttpStatusCode.BadRequest)

      val foundUser = userService.findById(id)
        ?: return@get call.respond(HttpStatusCode.NotFound)

      if (foundUser.username != extractPrincipalUsername(call))
        return@get call.respond(HttpStatusCode.NotFound)

      call.respond(
        message = foundUser.toResponse()
      )
    }
  }
}

private fun UserRequest.toModel(): User =
  User(
    id = UUID.randomUUID(),
    username = this.username,
    password = this.password
  )

private fun User.toResponse(): UserResponse =
  UserResponse(
    id = this.id,
    username = this.username,
  )

private fun extractPrincipalUsername(call: ApplicationCall): String? =
  call.principal<JWTPrincipal>()
    ?.payload
    ?.getClaim("username")
    ?.asString()

As we can see, after our changes, every GET /api/user request will be verified using the provider, which we specified without the name.

When we check logs, we should even see the confirmation:

Matched routes:
“” -> “api” -> “user” -> “(authenticate “default”)” -> “(method:GET)”

On the other hand, every request to GET /api/user/{id} will be handled by the another-auth provider:

“” -> “api” -> “user” -> “(authenticate another-auth)” -> “{id}” -> “(method:GET)”

Lastly, it’s worth mentioning that we changed one more thing:

authenticate("another-auth") {
  get("/{id}") {
    val id: String = call.parameters["id"]
      ?: return@get call.respond(HttpStatusCode.BadRequest)

    val foundUser = userService.findById(id)
      ?: return@get call.respond(HttpStatusCode.NotFound)

    if (foundUser.username != extractPrincipalUsername(call))
      return@get call.respond(HttpStatusCode.NotFound)

    call.respond(
      message = foundUser.toResponse()
    )
  }
}


private fun extractPrincipalUsername(call: ApplicationCall): String? =
  call.principal<JWTPrincipal>()
    ?.payload
    ?.getClaim("username")
    ?.asString()

In this handler, we obtain the JWTPrincipal (created inside the JwtService) in order to read the username. If it matches with the found user, then we simply return the user response. But if not, then we return 404 Not Found.

Summary

And that’s all for this tutorial on how to implement a REST API with Ktor and Kotlin and how to secure it with JWT access tokens.

If you would like to find the whole source code, then check out this GitHub repository.

Lastly, if you enjoyed this tutorial, then please do not forget to share it with other people on your social media (it will help me a lot) and check out the continuation for this post:

• how to implement a refresh token flow with Ktor,
• and how to add a role-based access control (RBAC) to the project.

The post Secure REST API with Ktor and JWT Access Tokens appeared first on Codersee blog- Kotlin on the backend.

Sooner or later, every developer will have to implement email-sending functionality in their application and it’s worth checking out various solutions, to pick the one that will best meet our needs.

And although the term “transactional emails” sounds complicated, in this tutorial I will prove how easily we can use them with Ktor and Kotlin.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

Prerequisites

Before we start, let’s see what exactly we will need for this tutorial.

First of all, we will need a MailerSend account. The free version will be fair enough for the purpose of learning and even simple projects.

Note: the above link is a referral and if you will purchase any paid plan, I’ll get a small commission for that. To be clear: this fact affects the merits of this article in no way 🙂

Additionally, you will need to have a domain, which you can verify. This is necessary, in order to work with any transactional email providers.

Configure Domain in MailerSend

I won’t go into much detail in this paragraph, because DNS settings will be dependent on your domain registrar. Nevertheless, let’s take look at how to add a new domain to MailerSend.

So, assuming we created our account and verified the email along with their policies, we should see the following:

As the next step, let’s click the Start button next to the “Add a sending domain”:

Right here, let’s specify the domain name- test.codersee.com in my case- and confirm with the Add domain button.

Nextly, we should see the Domain verification modal:

As we can see, in order to verify our domain, we need to navigate to our domain registrar and modify the DNS settings using the values specified in the modal. When it’s done, let’s click the Check/Re-check now button.

Note: DNS propagation can take some time, so don’t worry if you see the error messages (just like above). In such a case, give it some time and please get back to this page. MailerSend will send you an e-mail when everything is verified, as well.

If everything succeeded, we should see the following page:

One important note before we head to the next part. At this point, we will be able to send emails only to addresses and domains we previously verified– the e-mail address we use for registration and all addresses in a verified domain in our case.

Nevertheless, if you would like to send emails outside the domain, you will need to get approval.

Generate API Key

In order to send transactional emails with MailerSend in our Ktor app, we will need to generate a new API key.

To do so, let’s navigate to our domains (Email -> Domains in the left sidebar) and click the manage button:

On this page, we can manage API tokens and configure plenty of other things, like webhooks or tracking.

Anyway, let’s click the Generate new token button:

As we can see, right here we can specify the name and access granted to the new token. And although for simplicity we will stick with “Full access”, in real-life scenarios we should always follow the principle of least privilege.

Finally, let’s click the Create token:

As can be seen, the API token was created successfully and it’s time to save the value.

Note: please persist this value securely and never share it with anyone!

Generate Ktor Project

With all of that being done in MailerSend, we can finally switch to the Ktor & Kotlin part of our tutorial about transactional emails.

As always, let’s navigate to https://start.ktor.io/ and specify desired project settings:

Following, let’s click the Add plugins (we don’t need anything else), generate the project, and import it to our IDE.

Nextly, let’s add the Ktor client and Jackson dependencies inside the build.gradle.kts:

implementation("io.ktor:ktor-client-core-jvm:$ktor_version")
implementation("io.ktor:ktor-client-okhttp:$ktor_version")

implementation("io.ktor:ktor-client-content-negotiation:$ktor_version")
implementation("io.ktor:ktor-serialization-jackson:$ktor_version")

Of course, Jackson is not the only option here, and GSON, or kotlinx.serialization are well supported in Ktor, as well.

Configure Client

As the next step, let’s navigate to the application.conf file and add a custom MailerSend config:

mailersend {
  token = ${MAILERSEND_TOKEN}
  baseUrl = ${MAILERSEND_BASE_URL}
}

This way, we can pass the token and URL values securely through environment variables. And although the token will be unique, for the baseUrl, let’s set https://api.mailersend.com/v1/.

Nextly, let’s create the MailerSendClient.kt file and put the following:

fun Application.configureClient() {

  val token = environment.config.property("mailersend.token").getString()
  val baseUrl = environment.config.property("mailersend.baseUrl").getString()

  val mailerSendClient = HttpClient {
    install(ContentNegotiation) {
      jackson()
    }
  }

  runBlocking {
    // To be done in the next paragraphs
  }
}

As we can see, the above function reads configuration properties and installs the ContentNegotiation plugin using Jackson. Moreover, we’ve prepared the runBlocking block, where we will invoke our future functions.

Lastly, let’s navigate to the Application.kt file and make use of our config:

fun Application.module() {
  configureClient()
}

At this point, we can run our application and verify that it is working, as expected. If we forget to set environment variables correctly, we should see something like this:

Exception in thread “main” com.typesafe.config.ConfigException $ UnresolvedSubstitution: application.conf @ […] Could not resolve substitution to a value: ${MAILERSEND_BASE_URL}

Send Simple Email

With all of that done, we can finally start sending transactional emails. In this paragraph, we will learn how to send a simple email with MailerSend.

Implement EmailRequest

As the first step, let’s create a new data class called EmailRequest:

@JsonInclude(JsonInclude.Include.NON_NULL)
data class EmailRequest(
    val from: Recipient,
    val to: List<Recipient>,
    val subject: String,
    val text: String,
    val html: String,
    val variables: List<Variable>? = null
) {
    data class Recipient(
        val email: String,
        val name: String
    )

    data class Variable(
        val email: String,
        val substitutions: List<Substitution>
    ) {
        data class Substitution(
            @JsonProperty("var") val variable: String,
            val value: String
        )
    }
}

Basically, objects of this class will be serialized into JSONs when querying MailerSend API.

The @JsonInclude annotation states that if the value is set to null, then it should not be added to the JSON payload (so we won’t send "whatever": null) . Additionally, MailerSend requires us to send the “var” field inside the substitution. Nevertheless, var is a reserved keyword in Kotlin, so we have to make use of the @JsonProperty.

Use Ktor Client to Perform Requests

Following, let’s add a new function called sendSingleEmail:

suspend fun sendSingleEmail(
  mailerSendClient: HttpClient,
  url: String,
  token: String,
  emailRequest: EmailRequest
): HttpResponse =
    mailerSendClient.post(url) {
      headers {
        append(HttpHeaders.Authorization, "Bearer $token")
      }
      contentType(ContentType.Application.Json)
      setBody(emailRequest)
    }

As we can see, this one is responsible for sending POST requests to the passed URL with the Authorization header containing the Bearer token.

Moreover, the function takes the EmailRequest as an argument, which makes it reusable.

Send Transactional Client with Ktor Client

Lastly, let’s implement the sendSimpleMessage:

suspend fun sendSimpleMessage(
    mailerSendClient: HttpClient,
    baseUrl: String,
    token: String
) {
    val subject = "Hello from {\$company}!"
    val html = """
        Hello <b>{${'$'}name}</b>, nice to meet you!
    """.trimIndent()
    val text = """
        Hello {${'$'}name}, nice to meet you!
    """.trimIndent()

    val emailRequest = EmailRequest(
        from = EmailRequest.Recipient(
            email = "example@test.codersee.com",
            name = "Codersee"
        ),
        to = listOf(
            EmailRequest.Recipient(
                email = "example@test.codersee.com",
                name = "Pjoter"
            )
        ),
        subject = subject,
        html = html,
        text = text,
        variables = listOf(
            EmailRequest.Variable(
                email = "example@test.codersee.com",
                substitutions = listOf(
                    EmailRequest.Variable.Substitution(
                        variable = "company",
                        value = "Codersee"
                    ),
                    EmailRequest.Variable.Substitution(
                        variable = "name",
                        value = "Piotr"
                    )
                )
            )
        )
    )

    val response = sendSingleEmail(
        mailerSendClient = mailerSendClient,
        url = "$baseUrl/email",
        token = token,
        emailRequest = emailRequest
    )

    if (response.status == HttpStatusCode.Accepted)
        println("Email sent successfully.")
    else
        println("Error when sending email.")
}

And although the above code snippet consists of a lot of lines, it’s definitely easier than it looks.

Firstly, we prepare the EmailRequest instance, which after serialization, will become this JSON:

{
    "from": {
        "email": "example@test.codersee.com",
        "name": "Codersee"
    },
    "to": [
        {
            "email": "example@test.codersee.com",
            "name": "Pjoter"
        }
    ],
    "subject": "Hello from {$company}!",
    "html": "Hello <b>{$name}</b>, nice to meet you!"
    "variables": [
        {
            "email": "example@test.codersee.com",
            "substitutions": [
                {
                    "var": "company",
                    "value": "Codersee"
                },
                {
                    "var": "name",
                    "value": "Piotr"
                }
            ]
        }
    ]
}

Whereas most of the fields a pretty descriptive, let’s take a look at one, important thing- variables.

As we can see, we can inject variables into the email subject, or content by simply specifying them with a dollar sign inside curly braces, for example: {$someVariable}. This way, we can specify dynamic values for each recipient, like name and company in our example.

In the next lines, we simply send the request to the MailerSend API, and if the response status code is 202 Accepted, then the email was sent successfully:

Of course, in order to make it work, let’s invoke our function inside the configureClient:

runBlocking {
  sendSimpleMessage(mailerSendClient, baseUrl, token)
}

Send Emails With Templates

At this point, we already know how to send transactional emails with Ktor and MailerSend. Moreover, we’ve seen how to send HTML content, which is a great way to customize the template.

Nevertheless, if you’d like to learn how to make your life a bit easier and use a graphic builder for templates, then you’re gonna like this paragraph.

Prepare Template Using MailerSend Builder

As the first step, let’s navigate to the templates page: https://app.mailersend.com/templates.

Nextly, let’s click Create template button and select Drag & drop editor option:

This way, we’re redirected to the Template gallery, which contains ~50 predefined templates, which we can adjust to our needs. In this tutorial, we will select the Reset password:

After we click Choose, we’re redirected to the builder page, where we can make adjustments:

As we can see, when using the builder, we need to encapsulate variables with double curly brackets.

When we finish, let’s click the Save & Publish button and write down the Template ID on the next page- we will need it later.

Adjust EmailRequest Class

With that being done, let’s get back to the Ktor project and edit the EmailRequest class:

@JsonInclude(JsonInclude.Include.NON_NULL)
data class EmailRequest(
    val from: Recipient,
    val to: List<Recipient>,
    val subject: String,
    @JsonProperty("template_id") val templateId: String,
    val personalization: List<CustomPersonalization>
) {
    data class Recipient(
        val email: String,
        val name: String
    )

    data class CustomPersonalization(
        val email: String,
        val data: PersonalizationData
    ) {
        data class PersonalizationData(
            val name: String,
            @JsonProperty("my_super_generated_code") val code: String
        )
    }
}

This time, instead of specifying the content manually, we simply pass the template identifier and a list of personalizations.

In our case, the desired JSON looks, as follows:

{
  "from": {
    "email": "example@test.codersee.com",
    "name": "Codersee"
  },
  "to": [
    {
      "email": "example@test.codersee.com",
      "name": "Pjoter"
    }
  ],
  "subject": "Please Reset Your Password",
  "templateId": "v69oxl587pzl785k",
  "personalization": [
    {
       "email": "example@test.codersee.com",
       "data": {
         "name": "Pjoter",
         "code": "f7fcc37c-4b7a-4919-aa91-a5ac7edd55d7"
       }
     }
  ]
}

Implement Sending Functionality

With all of that prepared, let’s implement the sendMessageUsingTemplate:

suspend fun sendMessageUsingTemplate(
    mailerSendClient: HttpClient,
    baseUrl: String,
    token: String
) {
    val subject = "Please Reset Your Password"

    val emailRequest = EmailRequest(
        from = EmailRequest.Recipient(
            email = "example@test.codersee.com",
            name = "Codersee"
        ),
        to = listOf(
            EmailRequest.Recipient(
                email = "example@test.codersee.com",
                name = "Pjoter"
            )
        ),
        subject = subject,
        templateId = "v69oxl587pzl785k",
        personalization = listOf(
            EmailRequest.CustomPersonalization(
                email = "example@test.codersee.com",
                data = EmailRequest.CustomPersonalization.PersonalizationData(
                    name = "Pjoter",
                    code = UUID.randomUUID().toString()
                )
            )
        )
    )

    val response = sendSingleEmail(
        mailerSendClient = mailerSendClient,
        url = "$baseUrl/email",
        token = token,
        emailRequest = emailRequest
    )

    if (response.status == HttpStatusCode.Accepted)
        println("Email sent successfully.")
    else
        println("Error when sending email.")

As we can see, the logic itself remains almost exactly the same and the only thing, which changes, is the payload we send.

Lastly, let’s put the following in the configureClient and rerun the application:

runBlocking {
  sendSimpleMessage(mailerSendClient, baseUrl, token)
}

As a result, we should see the message “Email sent successfully.” and the following email in our inbox:

Handling ErrorsEmails With Templates

I simply couldn’t finish this article about sending transactional emails with Ktor and MailerSend without showing how to handle errors.

And although we try our best to avoid them, sooner or later they will pop up. Thankfully, MailerSend API informs us in a pretty neat way about any issues. For example:

{
    "message": "The template_id must be an integer. (and 2 more errors)",
    "errors": {
        "template_id": [
            "The template_id must be an integer."
        ],
        "to.0.email": [
            "The to.0.email field is required."
        ],
        "variables.0.email": [
            "The variables.0.email field does not exist in to.*.email."
        ]
    }
}

Create ErrorResponse

As the first step, let’s implement the ErrorResponse class:

data class ErrorResponse(
  val message: String,
  val errors: Map<String, List<String>>
)

We will use this simple data class to deserialize JSON response into the object.

Implement handleError

Nextly, let’s add the handleError function:

suspend fun handleError(response: HttpResponse) {
    val statusCode = response.status.value
    val errorBody =  response.body<ErrorResponse>()
    println("Email sending failed with status code $statusCode and message '${errorBody.message}'. Errors:")

    errorBody.errors.forEach { (fieldName, fieldErrors) ->
        println("  * field name: [$fieldName]. Messages:")
        fieldErrors.forEach { error -> println("    - $error") }
    }
}

As we can see, this function takes the HttpResponse from MailerSend API and parses the JSON into the ErrorResponse instance. Thanks to that we can iterate and display all the errors.

Of course, as the last step, we need to modify our conditional statement, to make use of this snippet:

if (response.status == HttpStatusCode.Accepted)
  println("Email sent successfully.")
else 
  println("Error when sending email.")

Sending Emails With Ktor And MailerSend Summary

And that’s all for this article about how to send transactional emails using Ktor, Kotlin, and MailerSend.

As always, you can find the source code in this GitHub repository.

Happy to hear your thoughts, feedback, or ideas in the comments 🙂

The post Sending Transactional Emails Using Ktor, Kotlin, and MailerSend appeared first on Codersee blog- Kotlin on the backend.