GraphQL API with Kotlin: Step-by-Step Tutorial for Beginners

Introduction: Why GraphQL and Kotlin are the Perfect Pair for Modern APIs

Modern web development requires flexible and performant APIs. REST, long the standard, often leads to the problem of over-fetching (when the server returns more data than needed) or under-fetching (when multiple requests are required to get complete information). GraphQL solves these problems by allowing the client to request only the necessary data in a single query.

Kotlin, in turn, is a modern, concise, and type-safe language that is well-suited for building reliable backend services. Thanks to the graphql-kotlin library from Expedia Group, creating a GraphQL API in Kotlin becomes simple and intuitive. In this tutorial, we will step-by-step create a full-fledged GraphQL API for managing a list of books.

What you will learn:

• How to set up a Spring Boot project with GraphQL support.
• How to define a GraphQL schema using Kotlin classes.
• How to implement Queries and Mutations.
• How to test the API via the built-in GraphiQL IDE.

Step 1: Project Setup and Dependencies

First, let's create a new Spring Boot project. We will use Gradle (Kotlin DSL) — this is the standard for modern Kotlin projects.

1.1. Creating the Project

You can use Spring Initializr or create the structure manually. We will need the following dependencies:

• Spring Web — to run the HTTP server.
• Spring Boot Starter GraphQL — the main integration.
• Kotlin Reflection — for the graphql-kotlin library to work.

1.2. The build.gradle.kts File

plugins {    id("org.springframework.boot") version "3.2.0"    id("io.spring.dependency-management") version "1.1.4"    kotlin("jvm") version "1.9.20"    kotlin("plugin.spring") version "1.9.20"}

group = "com.example"version = "0.0.1-SNAPSHOT"

java {    toolchain {        languageVersion = JavaLanguageVersion.of(17)    }}

repositories {    mavenCentral()}

dependencies {    implementation("org.springframework.boot:spring-boot-starter-web")    implementation("org.springframework.boot:spring-boot-starter-graphql")    implementation("com.expediagroup:graphql-kotlin-spring-server:7.0.1")    implementation("org.jetbrains.kotlin:kotlin-reflect")    testImplementation("org.springframework.boot:spring-boot-starter-test")}

1.3. The application.yml Configuration

spring:  graphql:    graphiql:      enabled: true  # Enable the built-in IDE for testing    schema:      locations: "classpath:graphql/**/"server:  port: 8080

Step 2: Defining the Schema and Data Model

In GraphQL, the schema is the contract between the client and the server. The graphql-kotlin library allows you to define the schema automatically based on Kotlin classes (code-first approach). This eliminates the need to write .graphqls files manually.

2.1. Creating the Data Model

Let's create a simple Book model and a repository for storing data in memory.

package com.example.graphqlkotlin.model

data class Book(    val id: String,    val title: String,    val author: String,    val year: Int)

2.2. Repository (in-memory)

package com.example.graphqlkotlin.repository

import com.example.graphqlkotlin.model.Bookimport org.springframework.stereotype.Repositoryimport java.util.concurrent.ConcurrentHashMap

@Repositoryclass BookRepository {    private val books = ConcurrentHashMap(        mapOf(            "1" to Book("1", "War and Peace", "Leo Tolstoy", 1869),            "2" to Book("2", "Crime and Punishment", "Fyodor Dostoevsky", 1866)\