Building a RESTful API with Kotlin and Spring Boot

In this tutorial, we will learn how to build a RESTful API using Kotlin and Spring Boot. We will cover the basics of creating a Spring Boot project, defining API endpoints, handling data persistence, error handling, and testing the API. By the end of this tutorial, you will have a fully functional RESTful API built with Kotlin and Spring Boot.

building restful api kotlin spring boot

Introduction

What is a RESTful API?

A RESTful API (Representational State Transfer) is an architectural style for designing networked applications. It allows different systems to communicate over HTTP using standard operations like GET, POST, PUT, and DELETE. RESTful APIs are stateless, meaning that each request from a client contains all the necessary information to fulfill the request. They are widely used in web development to create scalable and interoperable web services.

Benefits of using Kotlin and Spring Boot

Kotlin is a modern programming language that runs on the Java Virtual Machine (JVM). It offers concise syntax, null safety, and interoperability with Java, making it a great choice for developing backend applications. Spring Boot is a popular framework for building Java and Kotlin applications. It provides a set of conventions and tools to simplify the development process, allowing developers to focus on writing business logic instead of boilerplate code. By using Kotlin and Spring Boot together, we can create robust and efficient RESTful APIs.

Setting up the Development Environment

Before we start building our RESTful API, we need to set up our development environment. This involves installing Kotlin and creating a new Spring Boot project.

Installing Kotlin

To install Kotlin, you can follow the official documentation at kotlinlang.org. Kotlin can be installed using the command-line compiler or by using an IDE like IntelliJ IDEA or Android Studio.

Creating a new Spring Boot project

To create a new Spring Boot project, we can use the Spring Initializr. This is a web-based tool that generates a basic Spring Boot project structure for us. To create a new project, follow these steps:

Go to the Spring Initializr website.
Select the project's settings such as language (Kotlin), build system (Gradle or Maven), and Spring Boot version.
Add any required dependencies. For our RESTful API, we will need the Spring Web and Spring Data JPA dependencies.
Click on the "Generate" button to download the project zip file.

After downloading the project zip file, extract it to a directory of your choice. You now have a basic Spring Boot project set up and ready to be developed.

Configuring dependencies

Once we have our project set up, we need to configure the required dependencies. In this tutorial, we will be using the Spring Web and Spring Data JPA dependencies. To add these dependencies, open the build.gradle (or pom.xml if you chose Maven) file in the root directory of your project.

For Gradle, add the following lines to the dependencies block:

implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

For Maven, add the following lines to the dependencies block:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

These dependencies will provide us with the necessary tools to build our RESTful API.

Defining the API Endpoints

Now that we have our development environment set up, we can start defining our API endpoints. API endpoints are the URLs that clients can use to interact with our API. They define the operations that can be performed and the data that can be accessed or modified.

Creating the main controller

In Spring Boot, controllers are responsible for handling incoming requests and returning the appropriate responses. To create a controller, we can create a new Kotlin class and annotate it with @RestController. Let's create a UserController that will handle requests related to user data:

import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/users")
class UserController {
    // Controller methods will be defined here
}

In the above code, we have created a UserController class and annotated it with @RestController. The @RestController annotation combines @Controller and @ResponseBody, which means that the return value of each method will be automatically serialized into JSON and returned to the client.

Implementing GET endpoints

Now that we have our main controller set up, we can start implementing our API endpoints. Let's start with the GET endpoints, which will be used to retrieve user data.

@GetMapping("/{id}")
fun getUser(@PathVariable id: Long): User {
    // Retrieve the user with the given id from the database
    // Return the user object
}

@GetMapping
fun getAllUsers(): List<User> {
    // Retrieve all users from the database
    // Return a list of user objects
}

In the above code, we have defined two GET endpoints. The first endpoint retrieves a user with a specific ID, while the second endpoint retrieves all users. The @GetMapping annotation specifies the URL pattern for each endpoint, and the method parameters are used to extract data from the request (e.g., the user ID).

Implementing POST endpoints

Next, let's implement the POST endpoints, which will be used to create new users.

@PostMapping
fun createUser(@RequestBody user: User): User {
    // Save the user object to the database
    // Return the saved user object
}

In the above code, we have defined a POST endpoint that accepts a user object in the request body. The @RequestBody annotation tells Spring to deserialize the request body JSON into a user object. We then save the user object to the database and return the saved user object.

Handling request parameters and payloads

In addition to path variables and request bodies, we can also handle query parameters and request headers in our API endpoints. Let's see how we can do this.

@GetMapping("/search")
fun searchUsers(@RequestParam name: String): List<User> {
    // Retrieve users with the given name from the database
    // Return a list of user objects
}

In the above code, we have defined a GET endpoint /api/users/search that accepts a query parameter name. The @RequestParam annotation is used to extract the value of the query parameter from the request. We then retrieve users with the given name from the database and return a list of user objects.

Data Persistence

Now that we have defined our API endpoints, let's move on to data persistence. Data persistence is the process of storing and retrieving data from a database.

Setting up a database

To set up a database, we need to configure a database connection in our Spring Boot application. This can be done by adding the necessary properties to the application.properties (or application.yml) file in the src/main/resources directory.

For example, to configure a MySQL database, add the following properties to the application.properties file:

spring.datasource.url=jdbc:mysql://localhost:3306/mydatabase
spring.datasource.username=root
spring.datasource.password=secret
spring.jpa.hibernate.ddl-auto=update

In the above code, we have configured the database URL, username, password, and the Hibernate property ddl-auto to update. This means that Hibernate will automatically create or update the database schema based on our entity classes.

Defining entity classes

In Spring Boot, entity classes represent the data models that are stored in the database. To define an entity class, we can create a new Kotlin class and annotate it with @Entity and @Table. Let's create a User entity class:

import javax.persistence.*

@Entity
@Table(name = "users")
data class User(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long,
    val name: String,
    val email: String
)

In the above code, we have created a User class and annotated it with @Entity and @Table. The @Entity annotation tells Hibernate that this class represents a database table, and the @Table annotation specifies the name of the table. We have also defined three properties (id, name, and email) and annotated the id property with @Id and @GeneratedValue to specify that it is the primary key and its value will be automatically generated.

Implementing repository interfaces

In Spring Boot, repository interfaces are used to perform CRUD (Create, Read, Update, Delete) operations on the database. To implement a repository interface, we can create a new Kotlin interface that extends the JpaRepository interface provided by Spring Data JPA. Let's create a UserRepository interface:

import org.springframework.data.jpa.repository.JpaRepository

interface UserRepository : JpaRepository<User, Long>

In the above code, we have created a UserRepository interface that extends JpaRepository. This interface provides methods for performing CRUD operations on the User entity.

Performing CRUD operations

Now that we have our entity class and repository interface set up, we can start performing CRUD operations on the database. Let's update our controller methods to use the UserRepository.

@RestController
@RequestMapping("/api/users")
class UserController(private val userRepository: UserRepository) {

    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): User {
        return userRepository.findById(id).orElseThrow { NotFoundException("User not found") }
    }

    @GetMapping
    fun getAllUsers(): List<User> {
        return userRepository.findAll()
    }

    @PostMapping
    fun createUser(@RequestBody user: User): User {
        return userRepository.save(user)
    }
}

In the above code, we have injected the UserRepository into the UserController using constructor injection. We then use the repository methods (findById, findAll, and save) to perform the corresponding CRUD operations on the database.

Error Handling

In any API, it is important to handle errors gracefully and return appropriate error responses to the clients. Let's see how we can handle exceptions and return error responses in our API.

Handling exceptions

In Spring Boot, exceptions can be handled using exception handlers. To handle exceptions, we can create a new Kotlin class and annotate it with @ControllerAdvice. Let's create an ExceptionHandler class:

import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.RestControllerAdvice

@RestControllerAdvice
class ExceptionHandler {

    @ExceptionHandler(NotFoundException::class)
    fun handleNotFoundException(e: NotFoundException): ResponseEntity<String> {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.message)
    }
}

In the above code, we have created an ExceptionHandler class and annotated it with @RestControllerAdvice. We have also defined a method handleNotFoundException that handles the NotFoundException and returns a ResponseEntity with the appropriate HTTP status code and error message.

Returning appropriate error responses

In addition to handling exceptions, we can also return appropriate error responses for validation errors or other business logic errors. Let's update our controller methods to handle validation errors.

@PostMapping
fun createUser(@RequestBody @Valid user: User): User {
    return userRepository.save(user)
}

In the above code, we have added the @Valid annotation to the user parameter in the createUser method. This tells Spring to validate the user object and throw a MethodArgumentNotValidException if the validation fails. We can then handle this exception in our exception handler and return an appropriate error response to the client.

Testing the API

Now that we have implemented our API, it is important to test it to ensure that it works as expected. In Spring Boot, we can write unit tests and integration tests to test our controllers and API endpoints.

Unit testing the controllers

To test our controllers, we can create a new Kotlin class and annotate it with @SpringBootTest and @AutoConfigureMockMvc. Let's create a UserControllerTest class:

import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*
import org.springframework.test.web.servlet.result.MockMvcResultMatchers.*

@SpringBootTest
@AutoConfigureMockMvc
class UserControllerTest {

    @Autowired
    private lateinit var mockMvc: MockMvc

    @Test
    fun testGetUser() {
        mockMvc.perform(get("/api/users/1"))
            .andExpect(status().isOk)
            .andExpect(jsonPath("$.name").value("John Doe"))
            .andExpect(jsonPath("$.email").value("[email protected]"))
    }

    // Other test methods will be defined here
}

In the above code, we have created a UserControllerTest class and annotated it with @SpringBootTest and @AutoConfigureMockMvc. We have also injected the MockMvc object using field injection (@Autowired) and defined a test method testGetUser that performs a GET request to the /api/users/1 endpoint and asserts the response status and JSON content.

Integration testing the API endpoints

To test our API endpoints, we can create a new Kotlin class and annotate it with @SpringBootTest and @AutoConfigureMockMvc. Let's create an ApiTest class:

import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*
import org.springframework.test.web.servlet.result.MockMvcResultMatchers.*

@SpringBootTest
@AutoConfigureMockMvc
class ApiTest {

    @Autowired
    private lateinit var mockMvc: MockMvc

    @Test
    fun testGetUser() {
        mockMvc.perform(get("/api/users/1"))
            .andExpect(status().isOk)
            .andExpect(jsonPath("$.name").value("John Doe"))
            .andExpect(jsonPath("$.email").value("[email protected]"))
    }

    // Other test methods will be defined here
}

In the above code, we have created an ApiTest class and annotated it with @SpringBootTest and @AutoConfigureMockMvc. We have also injected the MockMvc object using field injection (@Autowired) and defined a test method testGetUser that performs a GET request to the /api/users/1 endpoint and asserts the response status and JSON content.

Conclusion

In this tutorial, we have learned how to build a RESTful API using Kotlin and Spring Boot. We have covered the basics of setting up the development environment, defining API endpoints, handling data persistence, error handling, and testing the API. By following this tutorial, you should now have a good understanding of how to build RESTful APIs with Kotlin and Spring Boot. Happy coding!