GraphQL API with Kotlin: Step-by-Step Practical Tutorial

Introduction: Why GraphQL and Kotlin Are a Perfect Pair?

In modern web development, choosing the right tool for creating an API determines development speed and ease of maintenance. GraphQL is a query language that allows clients to request only the data they need, eliminating the over-fetching and under-fetching problems inherent to REST. Kotlin, in turn, is a modern, concise, and safe language that is ideal for backend development, especially in conjunction with Spring Boot.

In this tutorial, we will practically build a full-fledged GraphQL API in Kotlin. You will learn how to set up a server, define a schema, implement queries and mutations, and test the finished API. By the end of the article, you will have a working project that can be used as a foundation for your applications.

1. Project Setup and Dependencies

First, let's create a new Spring Boot project with GraphQL support. We will use Spring for GraphQL — the official integration that makes the work as simple as possible.

1.1. Creating the Project

You can use Spring Initializr or any IDE (IntelliJ IDEA). Add the following dependencies:

• Spring Web
• Spring for GraphQL
• Spring Data JPA
• H2 Database (for simplicity)

The build.gradle.kts file should contain the following lines:

dependencies {    implementation("org.springframework.boot:spring-boot-starter-web")    implementation("org.springframework.boot:spring-boot-starter-graphql")    implementation("org.springframework.boot:spring-boot-starter-data-jpa")    runtimeOnly("com.h2database:h2")    testImplementation("org.springframework.boot:spring-boot-starter-test")}

1.2. Configuration

Let's create a simple Book entity and a repository for working with the database.

// Book.kt@Entitydata class Book(    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)    val id: Long = 0,    val title: String,    val author: String,    val year: Int)

// BookRepository.ktinterface BookRepository : JpaRepository<Book, Long>

2. Creating the GraphQL Schema and Controller

GraphQL uses strict typing. The schema defines what data is available and how it can be queried. In Spring for GraphQL, the schema can be described using annotations.

2.1. Defining the Schema via Code

Let's create a controller class that will handle GraphQL queries. Use the @QueryMapping annotation for reading data and @MutationMapping for modifications.

// BookController.kt@Controllerclass BookController(private val repository: BookRepository) {

    @QueryMapping    fun allBooks(): List<Book> = repository.findAll()

    @QueryMapping    fun bookById(@Argument id: Long): Book? = repository.findById(id).orElse(null)

    @MutationMapping    fun addBook(@Argument title: String, @Argument author: String, @Argument year: Int): Book {        val book = Book(title = title, author = author, year = year)        return repository.save(book)    }

    @MutationMapping    fun deleteBook(@Argument id: Long): Boolean {        if (repository.existsById(id)) {            repository.deleteById(id)            return true        }        return false    }}

2.2. Alternative: .graphqls Schema File

You can also define the schema in a separate schema.graphqls file in the resources/graphql folder:

type Query {    allBooks: [Book]    bookById(id: ID!): Book}

type Mutation {    addBook(title: String!, author: String!, year: Int!): Book    deleteBook(id: ID!): Boolean}

type Book {    id: ID!    title: S