Mastering GraphQL with Ktor: A Modern Networking Guide for Android

Source: Dev.to

Originally published on Medium:

Introduction

Modern Android apps demand flexible, efficient, and scalable networking solutions. While REST APIs have been the standard for years, GraphQL has emerged as a powerful alternative, especially for apps that need precise data fetching and reduced network overhead. Instead of hitting multiple endpoints to get different pieces of data, GraphQL allows you to ask for exactly what you need in a single request.

In my previous article, I discussed how to set up Ktor, the modern Kotlin‑first networking framework developed by JetBrains. We explored how it provides a lightweight alternative to Retrofit. If you haven’t read that yet, I highly recommend checking it out to get your base client set up. You can find the article here:

Exploring Ktor: A Modern Networking Framework for Kotlin

Now, let’s take things a step further and explore how you can integrate GraphQL with Ktor to build efficient APIs. Whether you are a beginner or looking to modernize your stack, this guide will cover everything from setup to making your first request.

What is GraphQL?

GraphQL is a query language for APIs that allows the client to request exactly the data it needs—nothing more, nothing less.

The major difference is that REST uses multiple endpoints with fixed response structures, while GraphQL uses a single endpoint with flexible queries to give optimized responses. This bandwidth efficiency is perfect for mobile apps where every kilobyte counts.

Why Use GraphQL with Ktor?

• Minimal Overhead – No need for heavy external libraries; keep your APK size small.
• Full Control – You define exactly how the request and response are handled.
• Multiplatform Ready – The same logic works seamlessly in Kotlin Multiplatform (KMP).
• Kotlin‑First – Coroutine‑based, no callbacks, and works smoothly with Clean Architecture & MVVM.

Setting Up the Project

Before integrating GraphQL, ensure you have Ktor in your Android project. Add these dependencies to your app‑level build.gradle.kts:

dependencies {
    implementation(platform("io.ktor:ktor-bom:3.1.2"))
    implementation("io.ktor:ktor-client-android")
    implementation("io.ktor:ktor-client-content-negotiation")
    implementation("io.ktor:ktor-serialization-kotlinx-json")
    implementation("io.ktor:ktor-client-logging")
}

Enable the Kotlin Serialization plugin in your root build.gradle.kts:

plugins {
    id("org.jetbrains.kotlin.plugin.serialization") version "2.1.20"
}

Understanding How GraphQL Works with Ktor

With GraphQL, every operation is usually a POST request to a single endpoint. The query or mutation is passed as a JSON body.

Define the Request Model

@Serializable
data class GraphQLRequest(
    val query: String,
    val variables: Map<String, Any>? = null
)

Define the Generic Response Wrapper

@Serializable
data class GraphQLResponse<T>(
    val data: T? = null,
    val errors: List<GraphQLError>? = null
)

@Serializable
data class GraphQLError(val message: String)

Making Your First Request

Let’s fetch a list of countries using a public GraphQL API. First, define your data models:

@Serializable
data class CountriesData(val countries: List<Country>)

@Serializable
data class Country(
    val code: String,
    val name: String,
    val emoji: String,
    val capital: String? = null
)

Implementation

suspend fun fetchCountries(): GraphQLResponse<CountriesData> {
    val countryQuery = """
        query {
            countries {
                code
                name
                emoji
                capital
            }
        }
    """.trimIndent()

    return httpClient.post("https://countries.trevorblades.com/graphql") {
        setBody(GraphQLRequest(query = countryQuery))
    }.body()
}

Handling Errors and Logging

GraphQL can return an HTTP 200 status even if there are errors in the query logic. Always check the error list:

val response = fetchCountries()
if (!response.errors.isNullOrEmpty()) {
    response.errors.forEach { error ->
        Log.e("GraphQL Error", error.message)
    }
}

For professional logging, I recommend using Timber. I’ve written a detailed guide on integrating Timber with Ktor in a later post.

Detailed Guide

A detailed guide on setting it up here: Effortless Android Logging with Timber and Kotlin

Read the article on Medium

Final Thoughts

Integrating GraphQL with Ktor is straightforward and gives Android developers a modern, flexible, and Kotlin‑native networking stack. It fits beautifully with MVVM and Clean Architecture. By leveraging a single unified HttpClient, you can handle both REST and GraphQL seamlessly.

GitHub Repository for Hands‑On Reference

To make this article more practical, I’ve published a public GitHub repository that demonstrates everything discussed above using a real GraphQL API.

The goal of this project is not just to “fetch data”, but to show how GraphQL should be integrated idiomatically in an Android application using Ktor—without forcing REST‑based abstractions on top of it.

📂 GitHub Repository:

https://github.com/your-username/ktor-graphql-android-example (replace with the actual URL)

GraphQL Example – Android (Jetpack Compose + Ktor)

Overview

A simple, clean Android sample that demonstrates how to consume a GraphQL API using Ktor within a Jetpack Compose application.
The project follows Clean Architecture and MVVM principles, showcasing idiomatic GraphQL handling without relying on REST‑style abstractions (e.g., fake HTTP status codes or generic response wrappers).

✨ Features

• ✅ GraphQL API integration using Ktor
• ✅ Jetpack Compose UI
• ✅ Clean Architecture (Data → Domain → UI)
• ✅ MVVM with unidirectional data flow
• ✅ Kotlin Coroutines
• ✅ Koin for dependency injection
• ✅ Proper GraphQL error handling (data vs errors)
• ✅ No Retrofit, no REST‑style CommonResponse

🔗 API Used (Free & Public)

Countries GraphQL API

https://countries.trevorblades.com/graphql

Sample query

query {
  countries {
    code
    name
    capital
  }
}

This API is:

• Completely free
• No authentication required
• Ideal for demos and learning

🏗️ Architecture Overview

Below is a high‑level diagram of the app’s layers and how they interact. Each component is kept independent to promote testability, maintainability, and scalability.

graph TD
    UI[UI (Jetpack Compose)] --> ViewModel[ViewModel (Android Architecture Components)]
    ViewModel --> Repository[Repository]
    Repository -->|Local| RoomDB[(Room Database)]
    Repository -->|Remote| Retrofit[(Retrofit API)]
    Repository -->|Cache| DataStore[(DataStore / SharedPreferences)]

Layer Breakdown

Interaction Flow

1. User Action – The UI emits an event (e.g., button click).
2. ViewModel – Receives the event, updates a StateFlow/LiveData, and calls the appropriate repository method.
3. Repository – Determines whether to fetch from the local cache (Room/DataStore) or make a network request (Retrofit).
4. Data Sources – Return data (or an error) back up the chain.
5. ViewModel – Emits the new UI state, which the Compose UI observes and re‑composes accordingly.

Tip: Keep the UI layer dumb – it should only render state and forward user intents. All logic belongs in the ViewModel or Repository, making it easy to unit‑test without Android dependencies.