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.

In this step-by-step guide, I would like to show you how to implement a REST API using Ktor, MongoDB, and KMongo.

If you haven’t heard about KMongo yet- it is a lightweight Kotlin toolkit for Mongo. Internally, it uses the core MongoDB Java Driver and exposes its features via Kotlin extensions. With this combination, we are sure that we’re using the recommended Java Driver, and additionally, we take advantage of the Kotlin less-verbose syntax.

In the end, I would like to add one more note. In this article, I will show you how to create MongoDB as a Docker container. If you have MongoDB already installed on your local machine, then you can just skip this part. Otherwise, please make sure that you have configured Docker properly in your local environment.

2. Generate Project

With that being said, let’s head to the Ktor Project Generator page and make a few adjustments.

Alternatively, you can generate the project within the app if you use IntelliJ IDEA Ultimate Edition

2.1. Adjust Ktor Settings

As the first step, let’s make sure that we set correctly the required properties:

Basically, the Project Name, Website, and Artifact are irrelevant and you can adjust it as you want. Nevertheless, to make sure that everything will be working as intended, please make sure to select the same Ktor version on this page.

2.2. Add Ktor Plugins

Nextly, let’s click the Plugins button, and add kotlinx.serialization to our project:

As we can see, two more plugins have been automatically: ContentNegotiation and Routing:

Unfortunately, we don’t have the possibility to add any dependencies required to work with MongoDB and Ktor, so for now, let’s click Generate Project button and import it to our IDE.

[elementor-template id=”9007393″]

3. Add KMongo Dependency

After we import the project, let’s head to the gradle.properties file and specify the version of KMongo we’d like to use:

kmongo_version=4.5.0

Following, let’s open the build.gradle.kts file and put the following lines:

val kmongo_version: String by project

// Inside the dependencies
implementation("org.litote.kmongo:kmongo:$kmongo_version")

4. Setup MongoDB Container

With all of the above being done, let’s prepare a MongoDB instance with Docker. Let’s open up the terminal and specify the following command:

docker run --name my_mongodb_cotainer -d -p 27017:27017 mongo:5.0.6

Basically, this with this one-liner we perform a few actions:

• with –name [name] we assign our custom name to the container. Otherwise, a random one will be generated
• -d, which is a shortcut for –detach, runs the container in the background and prints the container ID
• with -p host_port:container_port, we simply publish the 27017 port of the local machine to the same port of Mongo. In simple words, it is necessary to connect using localhost:27017 address
• in the end, we specify the image we would like to use- 5.0.6 in our case

To validate if everything is running as expected, let’s run the docker ps command and check the output:

docker run --name my_mongodb_cotainer -d -p 27017:27017 mongo:5.0.6
CONTAINER ID  IMAGE        COMMAND                 CREATED         STATUS         PORTS                     NAMES
3b4369dd37c6  mongo:5.0.6  "docker-entrypoint.s…"  11 minutes ago  Up 11 minutes  0.0.0.0:27017->27017/tcp  my_mongodb_cotainer

5. Ktor Configuration

If we made sure that the MongoDB instance is running, we can get back to our Ktor project and take a look at the configuration.

At this point, our project should consist of three files generated automatically: Application.kt, along with Routing.kt and Serialization.kt inside the plugins package. Please make sure that they are looking, as follows:

// Application.kt file:
fun main() {
  embeddedServer(Netty, port = 8080, host = "0.0.0.0") {
    configureRouting()
    configureSerialization()
  }.start(wait = true)
}

// Routing.kt file:
fun Application.configureRouting() {
  routing {
  }
}

// Serialization.kt file:
fun Application.configureSerialization() {
  install(ContentNegotiation) {
    json()
  }
}

To put it simply, these three files are responsible for setting up our server to respond on localhost:8080 and use kotlinx.serialization. Additionally, the Routing.kt is a skeleton, which we will use later to expose our endpoints.

6. Prepare Object Mapping

As the next step, let’s create a Person class:

data class Person(
  @BsonId
  val id: Id<Person>? = null,
  val name: String,
  val age: Int
)

As you can see, this simple class except for standard fields consists of the nullable id field annotated with @BsonId. Moreover, we need to use a parametrized Id<T> interface in order to let KMongo know that the Person class is the owner of the given ID. By making this field explicitly null, the id will be generated automatically, so that we won’t have to pass it explicitly on creation.

7. Add PersonDto

Following, let’s add a PersonDto to our project:

@Serializable
data class PersonDto(
  val id: String? = null,
  val name: String,
  val age: Int
)

Although it’s not necessary, this way we will separate objects used to communicate between client and our Ktor app from the ones used to communicate with MongoDB.

Additionally, let’s create a PersonExtension.kt file with two extension functions:

fun Person.toDto(): PersonDto =
  PersonDto(
    id = this.id.toString(),
    name = this.name,
    age = this.age
  )

fun PersonDto.toPerson(): Person =
  Person(
    name = this.name,
    age = this.age
  )

These helper functions will serve us as mappers later in the code.

8. Implement Error Response

As the last step of preparation, let’s create the ErrorResponse class:

@Serializable
data class ErrorResponse(val message: String) {
  companion object {
    val NOT_FOUND_RESPONSE = ErrorResponse("Person was not found")
    val BAD_REQUEST_RESPONSE = ErrorResponse("Invalid request")
  }
}

Again, this is not necessary but will be helpful when informing clients about errors.

9. Establish MongoDB Connection

With all the above being done, let’s create a PersonService:

class PersonService {

  private val client = KMongo.createClient()
  private val database = client.getDatabase("person")
  private val personCollection = database.getCollection<Person>()

}

Let’s have a look at each of the above lines:

• line 3- creates a Mongo instance using localhost and the default port (27017). If we would like to change connection details, then we can pass it as String, or ConnectionString to its overloaded versions
• line 4- obtains a Databse instance by the given name. If it does not exist, it will be created during the first insert
• line 5- gets a Collection (a Table in Mongo terminology). We will use this object to perform all operations

10. Insert Document To MongoDB

Following, let’s get to the heart of this tutorial- Ktor and MongoDB integration.

10.1. Add Create Function To Service

Let’s start by adding the create() function inside the PersonService:

fun create(person: Person): Id<Person>? {
  personCollection.insertOne(person)
  return person.id
}

As we can see, we use an already obtained MongoCollection instance to insert a provided Person object. If it is persisted successfully, then the ID will be updated with the value from the database, so that we can return it.

10.2. Expose POST Endpoint

As the next step, let’s head to the Routing.kt and insert the following lines:

val service = PersonService()

routing {
  route("/person") {
    post {
      val request = call.receive<PersonDto>()
      val person = request.toPerson()

      service.create(person)
        ?.let { userId ->
          call.response.headers.append("My-User-Id-Header", userId.toString())
          call.respond(HttpStatusCode.Created)
        } ?: call.respond(HttpStatusCode.BadRequest, ErrorResponse.BAD_REQUEST_RESPONSE)
    }
  }
}

Basically, the above logic is pretty straightforward. In the beginning, we obtain the JSON content of the request, which is deserialized to PersonDto instance. Then, we use our extension function to convert it to the Person class. If the document is persisted successfully, we simply return its id to the client setting the My-User-Id-Header and 201 Created status code. On the other hand, if the id is null, we then return an error response along with 400 Bad Request status.

10.3. Test POST Endpoint

Nextly, let’s run our application and perform a POST request:

POST http://localhost:8080/person

Payload:
{
  "name": "Piotr",
  "age": 55
}

Response Status: 
201 Created

Response Headers:
My-User-Id-Header: 6229a38236d4dc3abf0f3174 

So far, we don’t have endpoints to fetch the data, so let’s use MongoDB Compass to check.

10.4. Validate With MongoDB Compass

Let’s open up the application and simply click Connect:

Following, select the person database and collection in the left panel:

As we can see, the document was inserted correctly, which means that our Ktor setup works, as expected.

11. Obtain Documents From MongoDB

Nextly, let’s check how can we obtain documents from MongoDB using KMongo.

11.1. Add findAll() function

Let’s get back to the PersonService and implement the findAll() function:

fun findAll(): List<Person> =
  personCollection.find()
    .toList()

It’s a really simple function and later I will show you how to enhance it with additional filters.

11.2. Expose GET Endpoint

For now, let’s expose a simple GET endpoint:

get {
  val peopleList =
      service.findAll()
        .map(Person::toDto)

  call.respond(peopleList)
}

The above code simply uses our newly created function and maps each Person object using its extension method toDto().

11.3. Test GET Handler

Finally, let’s perform a GET request to see if everything is OK:

GET http://localhost:8080/person 

Response Status: 200 OK

Response Payload: 
[
  {
    "id": "6229a38236d4dc3abf0f3174",
    "name": "Piotr",
    "age": 55
  }
]

As we can see, the previously inserted MongoDB document is returned, so we can assume this part is done.

12. Get Document By ID

As the next step, let’s add the handler responsible for fetching people by their ID.

12.1. Implement findById() function

Let’s add the findById() within our service:

fun findById(id: String): Person? {
  val bsonId: Id<Person> = ObjectId(id).toId()
  return personCollection
    .findOne(Person::id eq bsonId)
}

One of the key features of KMongo is a type-safe query framework. As we can see above, to make sure that the appropriate argument type is passed to our database, we use a Kotlin property reference. This way, the code won’t compile if the input type won’t match the required one. In the next chapter, we will take a deeper look at this topic.

Alternatively, we can use .findOneById() and pass an ObjectId instance to it. Nevertheless, for the learning purpose I’ve deided to show you this approach, as well.

12.2. Create GET By ID Handler

For now, let’s insert a new handler to our codebase:

get("/{id}") {
  val id = call.parameters["id"].toString()

  service.findById(id)
    ?.let { foundPerson -> call.respond(foundPerson.toDto()) }
    ?: call.respond(HttpStatusCode.NotFound, ErrorResponse.NOT_FOUND_RESPONSE)
}

As we can see- firstly, we obtain the identifier from the request path. If the person with the given ID exists in MongoDB, then we return PersonDto to our Ktor app client. In other cases, we simply return 404 Not Found response.

12.3. Validate GET By ID Endpoint

Again, let’s make sure that the above theory meets practice:

GET (existing ID) http://localhost:8080/person/6229a38236d4dc3abf0f3174

Response Status: 200 OK

Response Payload: 
{
  "id": "6229a38236d4dc3abf0f3174",
  "name": "Piotr",
  "age": 55
}

GET (non-existing ID) http://localhost:8080/person/6229a38236d4dc3abf0f3175

Response Status: 404 Not Found

Response Payload: 
{
  "message": "Person was not found"
}

And again- that is the result we were expecting.

13. Search With Additional Filters

As the next step, let’s have a look at the KMongo filtering capabilities.

13.1. Create Type-Safe findByName() method

To do so, let’s add a findByName() function first:

fun findByName(name: String): List<Person> {
  val caseSensitiveTypeSafeFilter = Person::name regex name
  return personCollection.find(caseSensitiveTypeSafeFilter)
    .toList()
}

To find any document containing a given string in Mongo, we can use leverage $regex. Of course, there are other possibilities, like a $text operator, but it does not have its type-safe version in KMongo.

Also, it’s worth mentioning that the above filter is case-sensitive.

13.2. Add Case-Insensitive Regex Filter

However, if we would like to search for the documents containing the given text regardless of the case, then we can use the overloaded regex function:

val caseInsensitiveTypeSafeFilter = personCollection.find(
  (Person::name).regex(name, "i")
)

As we can see, the above regex extension function allows us to specify additional options. The “i” flag simply instructs MongoDB to match both upper and lower cases.

And again- this approach allows us to make sure that the appropriate argument type is passed each time.

13.3. Pass Filter As A String

Although it is more error-prone, the find() function allows us also to specify filters as String values:

val nonTypeSafeFilter = personCollection.find(
  "{name:{'\$regex' : '$name', '\$options' : 'i'}}"
)

In some cases, we don’t have any other possibility and in such a case we have to make sure to handle all the possible exceptions properly.

13.4. AND Operator

Another useful feature is filter chaining. Let’s learn how to chain filters with the AND operator:

val withAndOperator = personCollection.find(
  and(Person::name regex name, Person::age gt 40)
)

As we can see, the snippet from our Ktor app will look for all people persisted in MongoDB, which match the given name (case-sensitvie) and are older, than 40 years.

On the other hand, we can refactor the above code a bit:

val implicitAndOperator = personCollection.find(
  Person::name regex name, Person::age gt 40
)

When we pass multiple filters to the find() function, they are implicitly combined with AND operator.

13.5. OR Operator

Similarly, we can add the OR operator:

val withOrOperator = personCollection.find(
  or(Person::name regex name, Person::age gt 40)
)

13.6. Add Ktor Search Handler

To summarize the searching topic, let’s expose a new GET endpoint:

get("/search") {
  val name = call.request.queryParameters["name"].toString()

  val foundPeople = service.findByName(name).map(Person::toDto)

  call.respond(foundPeople)
}

This time, we use query parameters to obtain a name to look for. To put it simply, when searching for users with name John, the Ktor app client has to perform a GET localhost:8080/person/search?name=John request.

Given the fact I’ve presented various filters, I highly encourage you to test this endpoint on your own- by adding more data and validating each filter.

14. Update Document

As the second to last, let’s see how can we update the person by ID in our project.

14.1. Implement updateById()

Firstly, let’s add this code to our service:

fun updateById(id: String, request: Person): Boolean =
  findById(id)
    ?.let { person ->
      val updateResult = personCollection.replaceOne(person.copy(name = request.name, age = request.age))
      updateResult.modifiedCount == 1L
    } ?: false

As we can see, firstly we make use of our existing findById function. As a result, we get either found person object, or null. Following we make use of replaceOne() function and as an argument we pass the same person instance with updated name and age fields.

As this function is supposed to update document by its unique identifier, it returns true only when exactly 1 item was modified.

14.2. Create PUT Endpoint

As the next step, let’s expose a new endpoint:

put("/{id}") {
  val id = call.parameters["id"].toString()
  val personRequest = call.receive<PersonDto>()
  val person = personRequest.toPerson()

  val updatedSuccessfully = service.updateById(id, person)

  if (updatedSuccessfully) {
    call.respond(HttpStatusCode.NoContent)
  } else {
    call.respond(HttpStatusCode.BadRequest, ErrorResponse.BAD_REQUEST_RESPONSE)
  }
}

This one combines together a few concepts we’ve learned already and as a result either 204 No Content, or 400 Bad Request will be returned.

14.3. Test PUT Endpoint

And again, let’s see whether our endpoint is working correctly:

PUT (existing ID) http://localhost:8080/person/6229a38236d4dc3abf0f3174 

Request Payload: 
{ 
  "name": "Piotr- updated", 
  "age": 20
}

Response Status: 204 No Content

PUT (non-existing ID) http://localhost:8080/person/6229a38236d4dc3abf0f3173 

Request Payload: 
{ 
"name": "Piotr- updated", 
"age": 20
}

Response Status: 400 Bad Request

Response Payload:
{
  "message": "Invalid request"
}

This time, to validate if the data were persisted correctly, we can either use existing GET by ID endpoint or check with MongoDB Compass.

15. Delete Document

Finally, learn how to delete items from MongoDB in our Ktor project.

15.1. Create deleteById() Function

Let’s start by adding the deleteById() inside the service class:

fun deleteById(id: String): Boolean {
  val deleteResult = personCollection.deleteOneById(ObjectId(id))
  return deleteResult.deletedCount == 1L
}

This time, we simply create a new ObjectId and pass it to deleteOneById() function. Similarly, the operation was successful only if the deleted count equals 1.

15.2. Add DELETE Handler

Following, let’s implement the DELETE endpoint handler:

delete("/{id}") {
  val id = call.parameters["id"].toString()

  val deletedSuccessfully = service.deleteById(id)

  if (deletedSuccessfully) {
    call.respond(HttpStatusCode.NoContent)
  } else {
    call.respond(HttpStatusCode.NotFound, ErrorResponse.NOT_FOUND_RESPONSE)
  }
}

This time, we simply invoke deleteById function using the String identifier passed by API client. If the Person has been deleted successfuly, we return 204 No Content response. If that is not true, then we inform the client with 404 status.

15.3. Validate DELETE Endpoint

Finally, let’s see if everything was set up correctly:

DELETE (existing ID) http://localhost:8080/person/6229a38236d4dc3abf0f3174 

Response Status: 204 No Content

DELETE (we can use the same ID) http://localhost:8080/person/6229a38236d4dc3abf0f3174

Response Status: 404 Not Found
Response Payload:
{
  "message": "Person was not found"
}

As we can see, everything is working as expected.

16. Ktor With MongoDB and KMongo Summary

And that would be all for this step-by-step guide on creating a CRUD REST API with Ktor, MongoDB, and KMongo.

I really hope that my materials will help you to learn new things and will be happy if you would like to share some feedback with me using the contact form.

If you would like to get the full source code for this project, please refer to this GitHub repository.

The post A Guide To Ktor With MongoDB appeared first on Codersee blog- Kotlin on the backend.

In this step-by-step tutorial, I would like to show you how to create a simple REST API using Ktor, Ktorm, and PostgreSQL (aka Postgres).

Ktor is a free, open-source framework, which allows us to easily build connected applications. When it comes to server-side applications, we can treat it as a lightweight and powerful alternative to Spring Boot. Additionally, it was written in Kotlin programming language by its’ creators- the JetBrains team.

Ktorm, on the other hand, is a lightweight and efficient ORM Framework for Kotlin directly based on pure JDBC. Furthermore, combined with PostgreSQL makes an interesting combination for a REST API tech stack.

2. Generate Ktor Project

With all of that being said, let’s create the Ktor project (and in the next chapter, I will show you how to add Ktorm and PostgreSQL dependencies).

If you are the owner of IntelliJ Ultimate Edition, then it ships with Ktor support out of the box. Nevertheless, in this tutorial, we’ll focus on the alternative: https://start.ktor.io, which is pretty similar to the Spring Initializr page.

As the first step, let’s specify the project name along with other, necessary data:

Please remember about selecting the same Ktor version, so that the code from this tutorial will work for sure. Don’t worry about a sample code generated, we will take care of it later.

As the next step, let’s click the Add plugins button and add the kotlinx.serialization– we’ll use it to serialize our objects into JSON format:

As we can see, two other plugins have been added automatically: ContentNegotiation and Routing. Please do not remove them, we will need them later.

[elementor-template id=”9007393″]

2. Add Ktorm and PostgreSQL To Ktor

Nextly, let’s open up our Ktor Postgres project with IntelliJ and go to the gradle.properties file.

Unfortunately, the Project Generator does not allow us to add all of the necessary imports, so we will have to do it manually:

postgresql_driver_version=42.3.1
ktorm_version=3.4.1

As the next step, let’s add a few lines within the build.gradle.kts file and reload the Gradle project:

val ktorm_version: String by project
val postgresql_driver_version: String by project

dependencies {

// other dependencies

implementation("org.ktorm:ktorm-core:$ktorm_version")
implementation("org.ktorm:ktorm-support-postgresql:$ktorm_version")
implementation("org.postgresql:postgresql:$postgresql_driver_version")

}

As we can see, these dependencies are necessary in order to connect our Ktor application with the Postgres database.

3. Clean Up The Code

After that, let’s clean up the project a bit and delete the Routing.kt along with its invocation within the Application.kt.

The second file should now be looking, as follows:

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

Then, let’s go to the Serialization.kt file and remove unnecessary code, as well:

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

The above code will be necessary for JSON serialization.

4. Prepare PostgreSQL With Docker Compose

Basically, if you already have a PostgreSQL instance running on your machine, you can just skip the docker-compose part and just run the below SQL script.

Either way, let’s create the sql folder in the root directory and add the init-db.sql file:

CREATE TABLE book
(
  id   SERIAL NOT NULL,
  name varchar NOT NULL
);

INSERT INTO book(name) VALUES ('Book #1');
INSERT INTO book(name) VALUES ('Book #2');

We can clearly see, that after the script is run, a new table will be added and populated with test data.

Following, let’s go to the root of the Ktor project and add the docker-compose.yaml file with Postgres definition:

version: "3.9"
services:
  postgres-sandbox:
    image: postgres:14
    ports:
      - '5438:5432'
    volumes:
      - ./sandbox-db:/var/lib/postgresql/data
      - ./sql/init-db.sql:/docker-entrypoint-initdb.d/init-db.sql
    environment:
      - POSTGRES_NAME=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres

The above code is responsible for a few things:

• pulling the Docker image for PostgreSQL
• publishing the container’s 5432 port to the host’s 5438 (to put it simply- we will connect from our application using port 5438)
• running initialization script prepared above
• and finally, setting credentials through environment variables

To start our PostgreSQL instance, let’s run the below command:

docker-compose up

# To validate:
docker ps
CONTAINER ID IMAGE       COMMAND                CREATED       STATUS       PORTS                  NAMES
2f5716235039 postgres:14 "docker-entrypoint.s…" 6 minutes ago Up 6 minutes 0.0.0.0:5438->5432/tcp ktor-ktorm-postgresql_postgres-sandbox_1

As we can see, everything is working fine and now we will be able to connect our Ktor app with Postgres.

5. Implement DTOs

Following, let’s prepare request and response classes, which will be used in our REST API. Technically, we don’t have to do that, but it’s a good practice to keep them separate.

Let’s start with the BookRequest:

@Serializable
data class BookRequest(
  val name: String
)

Similarly, let’s implement the BookResponse and ErrorResponse:

@Serializable
data class BookResponse(
  val id: Long,
  val name: String
)

@Serializable
data class ErrorResponse(val message: String)

You might have noticed, that both classes are annotated with @Serializable (from kotlinx.serialization library). According to the documentation:

Applying Serializable to the Kotlin class instructs the serialization plugin to automatically generate implementation of KSerializer for the current class, that can be used to serialize and deserialize the class.

To put it simply, this annotation is necessary if we want to operate on these two classes in our REST API.

6. Add Entity And Columns Bindings

With all of that being done, let’s add the code responsible for object-relational mapping:

interface Book : Entity<Book> {
  companion object : Entity.Factory<Book>()

  val id: Long?
  var name: String
}

object Books : Table<Book>("book") {
  val id = long("id").primaryKey().bindTo(Book::id)
  val name = varchar("name").bindTo(Book::name)
}

It may seem a bit counterintuitive in the beginning, so let’s spend some time understanding it better.

The first one, Book, is a representation of the entity class, which will be used to operate on it. You might have already noticed, that it’s been declared as an interface- that’s a design requirement of Ktorm. (Ktorm 2.5 introduced the possibility to declare them as classes, but this approach has some limitations, which you can read more about here).

Additionally, you might be curious, what exactly does this line do?

companion object : Entity.Factory<Book>()

Basically, interfaces cannot be instantiated, but to help us with that, Ktorm provides an abstract class Entity.Factory. It overloads the invoke operator so that we will be able to create Book instances and initialize its properties pretty easily:

val newBook = Book {
  name = bookRequest.name
}

Finally, the second part, an object called Books is responsible for binding our entity with the database table.

It allows us to specify columns types, and names and wire them with our entity through the .bindTo() method. Whatsoever, we will use this object later, when working with our Ktor Postgres database connection.

7. Connect To PostgreSQL

As the next step, let’s implement the BookService and connect to the database:

class BookService {

  private val database = Database.connect(
    url = "jdbc:postgresql://localhost:5438/postgres",
    driver = "org.postgresql.Driver",
    user = "postgres",
    password = "postgres"
  )
}

As we can see, the connect function allows us to specify Ktor Postgres connection details. Please make sure that these values match the actual state in your case. As a result, we receive a new database object, which we will use to perform DB operations.

8. Implement Service Methods

With all of that being done, we can finally add logic responsible for books management.

Let’s go to the BookService and add 4 methods:

fun createBook(bookRequest: BookRequest): Boolean {
  val newBook = Book {
    name = bookRequest.name
  }

  val affectedRecordsNumber = 
    database.sequenceOf(Books)
      .add(newBook)

  return affectedRecordsNumber == 1
}

fun findAllBooks(): Set<Book> =
  database.sequenceOf(Books).toSet()

fun findBookById(bookId: Long): Book? =
  database.sequenceOf(Books)
    .find { book -> book.id eq bookId }

fun updateBookById(bookId: Long, bookRequest: BookRequest): Boolean {
  val foundBook = findBookById(bookId)
    foundBook?.name = bookRequest.name

  val affectedRecordsNumber = foundBook?.flushChanges()

  return affectedRecordsNumber == 1
}
fun deleteBookById(bookId: Long): Boolean {
  val foundBook = findBookById(bookId)

  val affectedRecordsNumber = foundBook?.delete()

  return affectedRecordsNumber == 1
}

8.1. Create Book

Let’s take a while to analyze each method:

fun createBook(bookRequest: BookRequest): Boolean {
  val newBook = Book {
    name = bookRequest.name
  }

  val affectedRecordsNumber = 
    database.sequenceOf(Books)
      .add(newBook)

  return affectedRecordsNumber == 1
}

As we can see, the createBook() creates a new Book instance (thanks to the companion object) and inserts it into the table using the database object.

The sequenceOf(), instantiates a new EntitySequence object. It exposes a sequence API, which we can use to perform DB operations, like querying or inserting data.

Finally, the .add() method inserts our entity into the database and returns the number of affected records.

The last line of this function simply validates, whether the number of affected records is equal to one (any other number indicates that something went wrong).

8.2. Fetching Books

Nextly, let’s check the querying functions:

fun findAllBooks(): Set<Book> =
  database.sequenceOf(Books).toSet()

fun findBookById(bookId: Long): Book? =
  database.sequenceOf(Books)
    .find { book -> book.id eq bookId }

They are pretty much the same, except for the fact, that in the second case the .find{} function will be translated to the WHERE clause in the generated SQL.

8.3. Update Book

As the next one, let’s check out the updateBookById():

fun updateBookById(bookId: Long, bookRequest: BookRequest): Boolean {
  val foundBook = findBookById(bookId)
  foundBook?.name = bookRequest.name

  val affectedRecordsNumber = foundBook?.flushChanges()

  return affectedRecordsNumber == 1
}

We can clearly see, that we can operate on the fetched entity, just like on any object in Kotlin. Nevertheless, for the changes to take effect, we must invoke the .flushChanges() function, which returns the affected records number.

8.4. Delete Book

Finally, the deleteBookById():

fun deleteBookById(bookId: Long): Boolean {
  val foundBook = findBookById(bookId)

  val affectedRecordsNumber = foundBook?.delete()

  return affectedRecordsNumber == 1
}

Although it’s performing a different action, the mechanism behind it remains the same.

9. Implement Book Routes

With all of that being done, we can finally add the necessary routes.

In Ktor, Routing is a core plugin responsible for handling incoming requests. If you’ve ever been working with Spring Boot before, then you may find it similar to the Controller concept.

9.1. Edit Application.kt

As the first step, let’s get back to the Application.kt and add configureBookRoutes() invocation:

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

9.2. Create BookRoutes.kt

Secondly, let’s add the BookRoutes.kt file with the necessary function:

fun Application.configureBookRoutes() {
  routing {
    route("/book") {
      val bookService = BookService()
      createBook(bookService)
      getAllBooksRoute(bookService)
      getBookByIdRoute(bookService)
      updateBookByIdRoute(bookService)
      deleteBookByIdRoute(bookService)
    }
  }
}

private fun Book?.toBookResponse(): BookResponse? =
  this?.let { BookResponse(it.id!!, it.name) }

To put it simply, the routing block installs a Routing feature in our application. On the other hand, the route builds a route to match the specified path. This way, we can keep relevant functions together and avoid duplicating the /book path for each of them.

When it comes to the toBookResponse(), this extension function will help us to convert Book entities into BookResponses.

9.3. Add Create Book Route

With this in mind, let’s implement the rest of the code step by step. As the first one, let’s add the createBook():

fun Route.createBook(bookService: BookService) {
  post {
    val request = call.receive<BookRequest>()

    val success = bookService.createBook(bookRequest = request)

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

The above code will be responsible for handling POST /book requests. As a word of explanation, the call.receive<BookRequest>() deserializes the content of the request (JSON) into the BookRequest instance. When the content cannot be translated, it throws ContentTransformationException (it’s worth to remember in real-life scenarios).

On the contrary, the call.respond() is responsible for sending responses to the client. We can clearly see that if creation is successful, the 201 Created is returned. However, if this is not the case, then the 400 Bad Request with an appropriate message is returned.

9.4. Implement Get All Books Route

As the next step, let’s add the getAllBooksRounte():

fun Route.getAllBooksRoute(bookService: BookService) {
  get {
    val books = bookService.findAllBooks()
      .map(Book::toBookResponse)

    call.respond(message = books)
  }
}

This one will be triggered on GET /book requests returning the list of books.

9.5. Add Get Book By Id Route

With that being done, let’s add the getBookByIdRoute() responsible for handling GET /book/{id} requests:

fun Route.getBookByIdRoute(bookService: BookService) {
  get("/{id}") {
    val id: Long = call.parameters["id"]?.toLongOrNull()
      ?: return@get call.respond(HttpStatusCode.BadRequest, ErrorResponse("Invalid id"))

    bookService.findBookById(id)
      ?.let { foundBook -> foundBook.toBookResponse() }
      ?.let { response -> call.respond(response) }
      ?: return@get call.respond(HttpStatusCode.BadRequest, ErrorResponse("Book with id [$id] not found"))
  }
}

This time, let’s focus on the call.parameters[“id”]. The Parameters property of the call is simply a map of case-insensitive names to a collection of String values. That’s why we have to use a safe ?.toLongOrNull() to obtain the value correctly. If the id is invalid, then the 400 Bad Request is returned.

The rest of the code is pretty straightforward- either the found book is mapped to the BookResponse instance and returned to the client, or a 400 Bad Request informing that the book with a given id was not found.

9.6. Insert Update and Delete Routes

Finally, let’s add the two routes responsible for handling PATCH /book/{id} and DELETE /book/{id} requests:

fun Route.updateBookByIdRoute(bookService: BookService) {
  patch("/{id}") {
    val id: Long = call.parameters["id"]?.toLongOrNull()
      ?: return@patch call.respond(HttpStatusCode.BadRequest, ErrorResponse("Invalid id"))

    val request = call.receive<BookRequest>()
    val success = bookService.updateBookById(id, request)

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

fun Route.deleteBookByIdRoute(bookService: BookService) {
  delete("/{id}") {
    val id: Long = call.parameters["id"]?.toLongOrNull()
      ?: return@delete call.respond(HttpStatusCode.BadRequest, ErrorResponse("Invalid id"))

    val success = bookService.deleteBookById(id)

    if (success)
      call.respond(HttpStatusCode.NoContent)
    else
      call.respond(HttpStatusCode.BadRequest, ErrorResponse("Cannot delete book with id [$id]"))
  }
}

As we can see, these functions use already described concepts, so we won’t go into much detail.

10. Test With cURL

Finally, let’s run the application and test it manually. For simplicity, we will use the cURL command. Alternatively, we could do that through Postman, or Insomnia.

10.1. GET /book

Let’s start by listing all books to validate both the endpoint and SQL init script:

curl localhost:8080/book

# Output
[
  {
    "id":1,
    "name": "Book #1"
  },
  {
    "id":2,
    "name":"Book #2"
  }
]

As we can see, everything is working correctly.

10.2. POST /book

As the second step, let’s create a new book:

curl -X POST 'localhost:8080/book' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Book #3"
  }'

# Then again: 
curl localhost:8080/book

# Output
[
  {
    "id":1,
    "name": "Book #1"
  },
  {
    "id":2,
    "name":"Book #2"
  },
  {
    "id":3,
    "name":"Book #3"
  }
]

10.3. GET /book/{id}

As the third step, let’s check whether fetching book details works:

curl localhost:8080/book/3

# Output:
{
  "id":3,
  "name":"Book #3"
}

curl localhost:8080/book/1234

# Output:
{
  "message":"Book with id [1234] not found"}
}

10.4. PATCH /book/{id}

After that, let’s validate the PATCH endpoint:

curl -X PATCH 'localhost:8080/book/3' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Book #3- edited"
  }'

# Then, let's check with GET:
curl localhost:8080/book/3

# Output:
{
  "id": 3,
  "name": "Book #3- edited"
}

10.5. DELETE /book/{id}

Finally, let’s delete created book:

curl -X DELETE 'localhost:8080/book/3'

# Then, let's check with GET:
curl localhost:8080/book/3

# Output:
{
  "message":"Book with id [3] not found"
}

11. Ktor With Ktorm And PostgreSQL Summary

And that would be all for this step-by-step guide on how to create REST API with Ktor, Ktorm, and PostgreSQL. I really hope you will find this material useful when working with Ktor. If you would like to see the source code, please refer to this GitHub repository.

If you find this one useful, then you may enjoy my newer article about Ktor and MongoDB.

As always- if you would like to ask me about anything, please do that in the comments section below, or through the contact form.

Previous articles, you might be interested in:

• Exception Handling with @RestControllerAdvice and @ExceptionHandler
• 16 IntelliJ Shortcuts That Will Boost Your Productivity
• SOLID Principles with Kotlin Examples

The post REST API With Ktor, Ktorm and PostgreSQL appeared first on Codersee blog- Kotlin on the backend.