A Guide To Ktor With MongoDB

1. Introduction

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.

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.