To get started we setup a project, run a webserver and provide a simple API

Project available in GitHub:


  • IntelliJ IDEA
  • JDK 1.8

Project Setup

  1. Create a new Gradle project in your IntelliJ IDE.
  2. Make sure to set your Project SDK to the correct JDK (in this case 1.8.0_111)
  3. And declare Java and Kotlin as Additional Libraries and Frameworks


The full build.gradle for Part 1 can be found at:

We will dive into more specifics below.

If set up correctly, your project comes with a basic build.gradle file which already includes your basic kotlin dependency as well as applying the java and kotlin plugins on your project, but since we are trying out new stuff we restructure the file using the plugins DSL for Gradle 2.1. More info on this here:

The plugins DSL allows for reduction of „version spam“ in your projects dependencies, more on this later. we can delete the buildscript block of our build.gradle as long as we insert the following plugin block:

Now we can drop the version definitions of these plugins from our dependencies block:

Now need to dive into some Kotlin specific stuff:

By default all classes in Kotlin are declared final, to use a keyword from classic Java. This interferes with some functions of the Spring framework. We can easily take care of this using the kotlin-spring plugin provided by Jetbrains:

and add the kotlin reflection library (required to open annotated classes)

Spring Boot

Spring Boot comes with a gradle plugin which takes care of spring dependencies for us.

To include simply add the plugin inside build.gradle as follows:

and add our web starter dependency:

Our first API endpoint

Let’s see if everything works as expected.

We start out by creating the source folder structure in our project root.

$ mkdirs -p src/main/kotlin/

and add the package to the newly created folder (in our case

inside the package Add a new Kotlin File/class and name it App.kt

This file will be our entry point.

Since Kotlin supports top level functions we can get our webserver started with as little effort as:

Notice, that the main() function is not a method of our App class, but a top-level function instead.

Hit Build, Run App.kt and your webserver will start up at http://localhost:8080

open http://localhost:8080 in your browser and you will find the standard Whitelabel Error Page (since no endpoint is defined for / )

Now lets define a simple /hello endpoint.

Use whatever structure you like to create a Controller class (Personally i keep all my controllers in a subpackage of the App package), and create a new Kotlin Class name HelloController containing the very simple functionality:

Now we annotate the class to let Spring know what we want it to do:

  • @RestController: This class shall be treated as a Controller
  • @RequestMapping: This function shall act as an endpoint

rebuild – run and visit http://localhost:8080/hello

If everything is up and running your server will now talk to you.


An API without tests is no API at all. In this section add a first test to our project to show in principle, how to test our previously created endpoint.

we start by replacing the testCompile line in the dependecies block of our previous build.gradle:

(Notice, once again we do not require a version number, due to the Spring Boot plugin taking care of that)

Create the appropriate file structure inside our /src folder

$ mkdirs -p /src/test/kotlin

Once again create your package (in this case and create a new Kotlin File/Class named HelloTest.kt

In this file we create our first test as follows:

Let’d dive into some of these annotations:

  • @SpringBootTest with RANDOM_PORT: Provides a real servlet environment. Embedded servlet containers are started and listening on a random port.
  • @Autowired: going into this too much would exceed this context of this exercise. We invite you to learn about Spring auto-wiring elsewhere, for our context, its only important that this gives us a minimal REST client to test our endpoints.

Build -> Run HelloTest.kt -> if everything shows up green we are good 😉


This concludes part 1 of our little series. Check back next time when we add MongoDB support to our web server.




S3 test image