Motivation

Kotlin is a popular language, but it is mostly associated with Android. This is not an accident: Google appointed it as a first-class language for Android. Since its conception, Kotlin was intimately related to the Android platform. But JetBrains has always emphasized its multiplatform nature. Nowadays Kotlin is used as a primary language for a variety of scenarios:

• iOS or Raspberry Pi (hence the development of Kotlin/Native)
• As a frontend language
• One of my favorites: serving as a backend language.

Recently I had to confront the dilemma of developing a small microservice (are all microservices small?) that would include some shared components with other J2EE applications. I would have total ownership over this microservice, as long as:

A) Other services and entities at my client could be able to operate with this microservice, and

B) Some shared components (i.e., models, DTOs…) could be shared among the platforms.

I decided to go fully Kotlin for it. Since I observed that for some folks Kotlin was still new in the backend, I thought it could be a good idea to provide a sort of Minimum Viable Product (MVP). The idea sounded attractive at first, and as I implemented it turned out to be faster and more efficient than I thought.

So, an MVP must include minimal functionality desired in a product. It should not get very complex, or the purpose gets killed. I came up with the following points that would be desired to have in an MVP for a backend service:

• A REST API providing CRUD operations for an entity.
• Documentation
• Testing
• Dependency Injection
• Environment separation

Choosing a small example as an entity that could serve, something as simple as a message entity could serve. Let’s consider a message being composed of an ID, a title, and some content.

As mentioned before, it can get much more complex the more features we add, but I considered this to be a good start for the MVP. Kotlin already makes a few things easy. I had to choose a few libraries to develop it as standard as I can. So after some research, I came up with the following thoughts:

• I have used Spring previously in Java. It does its job, it is pretty standard and I am happy overall with it. Since Spring Version 5.0 support for Kotlin was introduced. So this was going to be an obvious choice.
• Jackson is my choice for JSON conversation.

Many backend services based on Java use Maven out of habit, which is not a bad thing. However, I consider Gradle to be more deeply linked to Kotlin since its inception. So we will use Gradle for this tutorial. However, this could be easily ported to other platforms. Remember as well to have Gradle 4+ installed in your environment. The entire code has been uploaded to GitHub. You can direct yourself there anytime if you want to check the project entirely. However, if you want to start doing it from scratch (something we recommend in order to acquire knowledge solidly) follow the tutorial.

Let’s start getting our hands dirty.

Prerequisites

• If you do not have an existing infrastructure on your computer, we can recommend you to one of the *AMP (WAMP, LAMP, MAMP) alternatives. The installation is straightforward, and it will provide you a functioning MySQL database. Note you do not need the Apache and PHP parts of the package for this tutorial.
• We will also be using IntelliJ, since it provides a great integration with Kotlin and Spring.
• Postman to execute the requests.
• The user must feel comfortable developing basic Java web apps and understanding the layers beneath it (endpoints, database, etc).
• An SQL database reader. I use SequelPro for Macintosh and I can endorse it. Other OS will offer different alternatives. I have heard good things of SQLYog for Windows.

Creating our brand new project

In your IntelliJ environment, click on File -> New Project. Select Gradle, and click Next. The following screens refer to GroupID and Project name - choose the naming at your convenience.

Now that the project is created, we need to add the Gradle dependencies. We will be using Spring, Jackson and the MySQL connector. There are a few sub packages from Spring that will need to be added as well. Please, check that your main Gradle file contains the following lines within the block dependencies.

    // build.gradle
      
      dependencies {
          implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
          implementation('org.springframework.boot:spring-boot-starter-web')
          implementation('org.springframework.boot:spring-boot-starter-data-jpa')
          testCompile('org.springframework.boot:spring-boot-starter-test')
          runtime('mysql:mysql-connector-java')
          implementation "com.fasterxml.jackson.module:jackson-module-kotlin"
      }

To resolve the dependencies, make sure your block buildscript/dependencies looks like here:

    // build.gradle
      
    buildscript {
        ext.kotlin_version = '1.2.41' 
        ext.spring_boot_version = '2.0.0.RELEASE'
        ext.koin_version = '0.9.3'
    
        repositories {
            mavenCentral()
            jcenter()
        }
        dependencies {
            classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
            classpath "org.jetbrains.kotlin:kotlin-allopen:$kotlin_version"
            classpath "org.springframework.boot:spring-boot-gradle-plugin:$spring_boot_version"
        }
    }

Last, you need to apply the following plugins to your Gradle file

    // build.gradle
    
    apply plugin: 'kotlin'
    apply plugin: "kotlin-spring"
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'

Implementation of basic functionality

Let’s start with the proper code. A Spring application will always need to have an Application class. This is the main entry point to our MVP. Create a class called Application.kt in your root folder, and include the following code:

    // src/main/kotlin/com/kotlinmvpweb/demo/Application.kt
    
    import org.springframework.boot.SpringApplication
    import org.springframework.boot.autoconfigure.SpringBootApplication
    
    @SpringBootApplication
    class Application
    
    fun main(args: Array<String>) {
        SpringApplication.run(Application::class.java, *args)
    }

Now that our Spring application has been specified, we are going to define our entity. We agreed on using an entity called Message, but essentially every other class will serve for that purpose. We want to showcase how straightforward this implementation results with Kotlin.

As a reminder, we agreed on our Message being composed of ID, title, and content. Define your following class (Message.kt) in a new package (model) within your root folder:

    // src/main/kotlin/com/kotlinmvpweb/demo/model/Message.kt
    
    import javax.persistence.Entity
    import javax.persistence.GeneratedValue
    import javax.persistence.GenerationType
    import javax.persistence.Id
    import javax.validation.constraints.NotBlank
    
    @Entity
    data class Message (
            @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
            val id: Long = 0,
    
            @get: NotBlank
            val title: String = "",
    
            @get: NotBlank
            val content: String = ""
    )

Java would have traditionally needed a group of setters/getters to provide access to the fields. Kotlin simplifies this by using data classes.

Let’s create our Spring repository. Create the following class MessageRepository in a package called repository in your root folder:

    // src/main/kotlin/com/kotlinmvpweb/demo/repository/MessageRepository.kt
    
    import com.kotlinmvpweb.demo.model.Message
    import org.springframework.stereotype.Repository
    import org.springframework.data.jpa.repository.JpaRepository
    
    @Repository
    interface MessageRepository : JpaRepository<Message, Long>

By creating this interface we are actually fulfilling two purposes:

• When we extend from JpaRepository, we essentially get all the required CRUD methods we will later need for our class message.
• This will allow the Spring repository infrastructure to scan the classpath for this interface and create a Spring bean for it.

Now let’s create our last class to complete the basic setup. Create a folder controller in your root folder, a new class called MessageController.kt ` with the following content:

    // src/main/kotlin/com/kotlinmvpweb/demo/controller/MessageController.kt
    
    import com.kotlinmvpweb.demo.model.Message
    import com.kotlinmvpweb.demo.repository.MessageRepository
    import org.springframework.http.HttpStatus
    import org.springframework.http.ResponseEntity
    import org.springframework.web.bind.annotation.*
    import javax.validation.Valid
    
    
    
    @RestController
    @RequestMapping("/api")
    class MessageController(private val messageRepository: MessageRepository) {
    
        @GetMapping("/messages")
        fun getAllmessages(): List<Message> =
                messageRepository.findAll()
    
    
        @PostMapping("/messages")
        fun createNewMessage(@Valid @RequestBody message: Message): Message =
                messageRepository.save(message)
    
    
        @GetMapping("/messages/{id}")
        fun getMessageById(@PathVariable(value = "id") messageId: Long): ResponseEntity<Message> {
            return messageRepository.findById(messageId).map { message ->
                ResponseEntity.ok(message)
            }.orElse(ResponseEntity.notFound().build())
        }
    
        @PutMapping("/messages/{id}")
        fun updateMessageById(@PathVariable(value = "id") messageId: Long,
                              @Valid @RequestBody newMessage: Message): ResponseEntity<Message> {
    
            return messageRepository.findById(messageId).map { existingMessage ->
                val updatedMessage: Message = existingMessage
                        .copy(title = newMessage.title, content = newMessage.content)
                ResponseEntity.ok().body(messageRepository.save(updatedMessage))
            }.orElse(ResponseEntity.notFound().build())
    
        }
    
        @DeleteMapping("/messages/{id}")
        fun deleteMessageById(@PathVariable(value = "id") messageId: Long): ResponseEntity<Void> {
    
            return messageRepository.findById(messageId).map { message  ->
                messageRepository.delete(message)
                ResponseEntity<Void>(HttpStatus.OK)
            }.orElse(ResponseEntity.notFound().build())
        }
    }

Each method provides a different HTTP Endpoint (using the HTTP Operations GET, POST, PUT or DELETE based on the annotation). Inside the function, the logic for the operation is included: in our case, there is no complex logic, just a simple database operation using Spring. Check also the placeholder {id} in some of the methods - this must be specified in the query URL.

Lastly, we need to create a configuration file for Spring. In this file, we will write our information for accessing the database and some extra fields. Create a file called application.properties within your folder resources including this:

    // src/main/resources/application.properties
    
    ## Spring DATASOURCE (DataSourceAutoConfiguration & DataSourceProperties)
    spring.datasource.url = jdbc:mysql://localhost:3306/your-db?autoReconnect=true&useUnicode=true&characterEncoding=UTF-8&allowMultiQueries=true&useSSL=false
    spring.datasource.username = root
    spring.datasource.password = root
    
    # The SQL dialect makes Hibernate generate better SQL for the chosen database
    spring.jpa.properties.hibernate.dialect = org.hibernate.dialect.MySQL5InnoDBDialect
    
    # Hibernate ddl auto (create, create-drop, validate, update)
    spring.jpa.hibernate.ddl-auto = update

If you have installed one of the *AMP platforms, you generally have to start the database through their interface. In my case, I have installed MAMP. WAMP and LAMP have similar interfaces. Open the starting screen, and click on the button Start Servers.

This will initialise the database. Make sure that the database name you have referred to in your application.properties file exists beforehand (in our example, the name is your-db). If you open SequelPro, you can create a new database by clicking on Database → Add Database. The default encoding and collation will suffice for our example.

Now, it is time to run your example. IntelliJ generally creates a run configuration with default values that works out for most of the environments. If you click on Run → Run Application, there should be a default option. If there isn’t, click on Run → Edit Configurations. In the screen that pops up, click on + Spring Boot. This will create a default Spring Boot run configuration. You need to provide some values in this screen (mainly the name of your Application class). See in the following screen an example of configuration (the other options are advanced and not needed for this tutorial):

You are ready to go. When your configuration is set up, click on Run → Run Your-Configuration-Name and the application will start!

Let’s see how this works. Open Postman, and execute a POST request against http://localhost:8080/api/messages sending the following JSON object in the body:

    {
        "id": 8,
        "title": "A message",
        "content": "A content"
    }

If everything has worked out, the backend will return you the object that has been created.

As mentioned, you can perform all the HTTP Operations (PUT, DELETE, POST, GET)

Documentation

The language that is being used in Kotlin to document code is called KDoc. If you are familiar with JavaDoc, they both work pretty similarly. KDoc has been extended to support Kotlin particularities. There is an open source alternative I would like to mention here, and it is called Dokka. Dokka has some more functionality than KDoc itself, and you might want to check their GitHub repository. Coming back to Dokka, let’s see how the syntax would work. Let’s first write a documentation block for our class MessageController:

    /**
     * This class is a controller that handles messages
     *
     * @property messageRepository the repository of messages
     * @constructor Creates an empty controller.
     */

So far, simple and it might remind the potential reader of JavaDoc. The properties are specified through a @property annotation. The behavior of the constructor through the annotation @constructor. Let’s observe how this would work in the case of a function createNewMessage:

    /**
      * Stores a message in our backend
      * @return the inserted message in case it was successful
      */  

Again, and similarly to JavaDoc, we do include a short description of the function behavior and functionality. We use the annotation @return to describe what the function will return.

Logging your code

Logging is an overdiscussed topic in terms of usefulness and practicality. There are fierce discussions whether one library is better than another one, or whether a pattern is more suitable than a previously used. Same discussions happen all the time with code styling. I like to present here a TL;DR: do not lose too much time on those arguments, and use the library or mechanism that best suits your needs. Most of the logging frameworks have a very similar functionality. For our purpose, we will use kotlin-logging, but any other framework can serve you if you feel like it.

In order to add kotlin.logging to your project, make sure you add the following lines to your build.gradle file:

    compile 'io.github.microutils:kotlin-logging:1.5.4'

Now you are ready to go.

Testing your code

Testing is a crucial part of any software system. It allows us to create iterative improvements and add new features while keeping safe the already constructed code. JetBrains provides the library kotlin.test, which provides annotations and a set of utility functions for your tests. This library includes a set of modules. One of the most interesting is kotlin-test-junit5. This module provides an implementation of Asserter on top of JUnit 5.

In order to start developing your own tests, you need to import the library kotlin.test in your project. Make sure the following lines have been included in your Gradle file.

    testCompile "org.jetbrains.kotlin:kotlin-test-junit"

After synchronizing your Gradle file, you should be able to access the classes included within this library. Now, next to your main folder, create the following path: test/kotlin/com/kotlinmvpweb/demo. This folder will be the responsible to host your tests. Now create inside a Kotlin file that can be named HelloWorldTest.kt. Within the folder, write the following content:

    // src/test/kotlin/com/kotlinmvpweb/demo/ExampleTests.kt
    
    import mu.KotlinLogging
    import org.junit.After
    import org.junit.Assert
    import org.junit.Before
    import org.junit.Test
    import kotlin.test.assertTrue
    
    class ExampleTests {
    
        private val logger = KotlinLogging.logger {}
    
        @Before
        fun prepareYourTest() {
            logger.debug { "We are preparing our test" }
        }
    
        @Test
        fun exampleTestInline() {
            logger.debug { "We are executing our test" }
            assertTrue {
                logger.debug { "Here an assertion will take place" }
                true
            }
        }
    
        @Test
        fun testOk() {
            Assert.assertEquals("A string", "A different string" )
        }
    
        @After
        fun after() {
            logger.debug { "We finished executing our test" }
        }
    }

The code is easy to read. You see that we have two functions annotated with @Before and @After. Those functions will be executed before and after the actual tests are executed, in case you need to set up or tear down any of your variables. This was actually the syntax in Junit 3.x, fortunately, the world always gravitates towards a better place. The functions executing a test are annotated with @Test. One of them includes an inline assertion, whereas the other one includes an assert function from the JUnit suite. Tests can get more complex as your software grows but is not the nature of this tutorial to provide a deep inside. We can refer you to a nice article written by Philipp Hauer where he explores it more intensively.

If you want to run the tests, you just need to right click on the test file, and select Run filename.kt The tests will execute, and a panel will be displayed at the bottom showing the result. You can change the test output, to see how some of them might fail and how some of them might pass.

Conclusion

After reading this article, a reader should have ended up with a functioning MVP. This MVP provides a backend, CRUD operations to the database and its correspondent endpoints. This is just the beginning of the journey. Software gets unapologetically complex over time. But it is paramount to start with a stable and fresh basis in order to provide sustainable growth. The repository can be accessed here.

After this introduction, a reader might want to take a look at the following topics:

• Dependency injection
• Further architecturing the app
• Advanced testing
• Database migrations

I would like to thank my colleagues and friend Inaki Villar and Marius Budin for their friendly and helpful review.