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

Introduction to GraphQL API with Kotlin

GraphQL is a query language for APIs developed by Facebook that allows clients to request only the data they actually need. Unlike REST, where each endpoint returns a fixed data structure, GraphQL provides flexibility and control. Kotlin, being a modern statically typed language for the JVM, is ideal for creating such APIs due to its conciseness and safety. In this tutorial, we will step by step create a simple GraphQL server in Kotlin using the graphql-kotlin library and Spring Boot.

By the end of this article, you will learn:

• How to set up a Kotlin project with Gradle
• How to define a GraphQL schema (types, queries, mutations)
• How to implement resolvers for handling queries
• How to test the API via GraphQL Playground

Step 1: Project Setup and Dependencies

First, let's create a new Kotlin project using Gradle. We will use Spring Boot to simplify configuration and graphql-kotlin-spring-server for GraphQL integration.

Creating the Basic Project

Create a project directory and a 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.21"    kotlin("plugin.spring") version "1.9.21"}

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

java {    sourceCompatibility = JavaVersion.VERSION_17}

repositories {    mavenCentral()}

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

tasks.withType {    kotlinOptions {        freeCompilerArgs += "-Xjsr305=strict"        jvmTarget = "17"    }}

Then create the main application class in src/main/kotlin/com/example/Application.kt:

package com.example

import org.springframework.boot.autoconfigure.SpringBootApplicationimport org.springframework.boot.runApplication

@SpringBootApplicationclass Application

fun main(args: Array<String>) {    runApplication<Application>(*args)}

Step 2: Defining the Data Model and GraphQL Schema

GraphQL uses strict typing. Let's define a simple data model — a book (Book) and an author (Author).

Creating Data Classes

Create the file src/main/kotlin/com/example/model/Book.kt:

package com.example.model

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

data class Author(    val id: String,    val name: String,    val nationality: String)

The graphql-kotlin library will automatically generate GraphQL types based on these data classes. Each field will become a field in the schema.

Resolvers for Queries

Now let's create a service that will provide the data. Create src/main/kotlin/com/example/service/BookService.kt:

package com.example.service

import com.example.model.Authorimport com.example.model.Bookimport org.springframework.stereotype.Service

@Serviceclass BookService {    private val books = mutableListOf(        Book("1", "War and Peace", Author("a1", "Leo Tolstoy", "Russia"), 1869),        Book("2", "Crime and Punishment", Author("a2", "Fyodor Dostoevsky", "Russia"), 1866),        Book("3", "1984", Author("a3", "George Orwell", "United Kingdom"), 1949)    )

    fun getAllBooks(): List<Book> = books    fun getBookById(id: String): Book? = books.find { it