Modern mobile applications depend heavily on APIs to communicate with backend servers.

Whether you are building an e-commerce application, social media app, booking platform, financial application, or business management system, your mobile application usually needs to:

• Send login requests
• Fetch products
• Upload user data
• Retrieve orders
• Update profiles
• Send form submissions
• Handle authentication
• Process JSON responses

With Kotlin Multiplatform (KMP), developers can share networking and API-related code between platforms such as Android and iOS.

One popular solution for multiplatform networking is Ktor Client.

Ktor Client is designed to work with Kotlin Multiplatform and allows developers to build HTTP clients that can be shared across supported platforms.

In this complete guide, you’ll learn how Kotlin Multiplatform networking works, how Ktor Client fits into a KMP architecture, how to make GET and POST requests, work with JSON, handle errors, add authentication, use repositories, and organize a production-ready API layer.

---

What Is Kotlin Multiplatform Networking?

Kotlin Multiplatform networking means creating API communication logic that can be reused across multiple platforms.

Instead of creating completely separate API implementations:

Android
   ↓
Android API Code

iOS
   ↓
iOS API Code

you can create shared networking logic:

             Shared KMP
                 |
             Ktor Client
             /        \
            ↓          ↓
        Android       iOS

This can significantly reduce duplicated networking code.

---

What Is Ktor?

Ktor is a Kotlin-based framework developed by JetBrains.

It can be used for:

• HTTP clients
• HTTP servers
• REST APIs
• Networking
• Authentication
• JSON serialization
• WebSockets
• Multiplatform applications

For Kotlin Multiplatform applications, Ktor Client is particularly useful because it provides a multiplatform HTTP client architecture.

---

Why Use Ktor Client With Kotlin Multiplatform?

Traditional Android applications can use Android-specific networking libraries.

However, if you want to share networking code between Android and iOS, you need a solution that supports multiple platforms.

Ktor Client is designed for this use case.

A typical architecture looks like:

Android UI             iOS UI
     |                    |
     +---------+----------+
               |
         Shared KMP Code
               |
          Repository
               |
          Ktor Client
               |
             API
               |
           Backend

The shared layer can contain:

• API interfaces
• HTTP requests
• JSON serialization
• Request models
• Response models
• Error handling
• Repository logic

---

Ktor Client Architecture in KMP

A clean architecture can look like:

UI
 ↓
ViewModel
 ↓
Use Case
 ↓
Repository
 ↓
API Service
 ↓
Ktor HTTP Client
 ↓
Backend API

For example:

ProductScreen
     ↓
ProductViewModel
     ↓
GetProductsUseCase
     ↓
ProductRepository
     ↓
ProductApi
     ↓
Ktor Client
     ↓
REST API

This keeps the networking layer independent from the UI.

---

Ktor Client and Source Sets

A KMP project commonly contains:

shared/
└── src/
    ├── commonMain/
    ├── commonTest/
    ├── androidMain/
    └── iosMain/

Most networking code can be placed inside:

commonMain

Platform-specific HTTP engine configuration can be provided for Android and iOS.

Conceptually:

commonMain
    |
    +--- Ktor Client configuration
    |
    +--- API services
    |
    +--- Models
    |
    +--- Repositories
    |
    +--- JSON serialization
    |
    +--- Error handling
    |
    +--- Authentication

Platform source sets can provide the appropriate engine implementation.

---

Ktor HTTP Engines

Ktor Client uses an HTTP engine to perform network requests.

The exact engine depends on the target platform.

For example, a project can use:

Android → Android-compatible Ktor engine
iOS     → Darwin engine

The important idea is that your application-level networking code can remain shared while the low-level HTTP implementation is selected for each platform.

---

Adding Ktor Dependencies

The exact dependency versions change over time, so use a current compatible Ktor release for your project.

A typical KMP project requires Ktor client modules such as:

implementation("io.ktor:ktor-client-core:<version>")
implementation("io.ktor:ktor-client-content-negotiation:<version>")
implementation("io.ktor:ktor-serialization-kotlinx-json:<version>")

You also need platform-specific engine dependencies.

For Android and iOS, the selected engine is added to the appropriate source set.

For example, conceptually:

commonMain
    ktor-client-core
    content-negotiation
    serialization-kotlinx-json

androidMain
    Android engine

iosMain
    Darwin engine

Always check Ktor’s documentation and your Kotlin/KMP version compatibility before choosing dependency versions.

---

Creating a Basic Ktor Client

A simple shared client can look like:

val httpClient = HttpClient {
    install(ContentNegotiation) {
        json()
    }
}

The ContentNegotiation plugin allows Ktor to handle structured formats such as JSON.

For production applications, you’ll usually configure additional settings such as:

• Logging
• Timeouts
• Default headers
• Authentication
• Response validation
• Serialization

---

Configuring JSON Serialization

Most REST APIs communicate using JSON.

For example:

{
  "id": 1,
  "name": "John",
  "email": "john@example.com"
}

Ktor can work with Kotlin serialization.

Create a serializable model:

@Serializable
data class User(
    val id: Int,
    val name: String,
    val email: String
)

Now Ktor can deserialize a JSON response into a Kotlin object.

---

What Is @Serializable?

@Serializable tells Kotlin serialization that a class can be serialized and deserialized.

Example:

@Serializable
data class Product(
    val id: Int,
    val name: String,
    val price: Double
)

This model can be used for JSON requests and responses.

---

Making a GET Request With Ktor

Suppose your backend provides:

GET /users

A basic request can look like:

val users: List<User> =
    client.get("https://api.example.com/users").body()

The response is converted into Kotlin objects.

A more structured API service might be:

class UserApi(
    private val client: HttpClient
) {

    suspend fun getUsers(): List<User> {
        return client
            .get("https://api.example.com/users")
            .body()
    }
}

---

Understanding suspend

Network requests can take time.

Therefore, Ktor requests are commonly called from coroutine-based code.

Example:

suspend fun getUsers(): List<User> {
    return client
        .get("https://api.example.com/users")
        .body()
}

A suspend function can be called from a coroutine or another suspend function.

This allows the application to perform asynchronous operations without blocking the current execution flow.

---

Making a POST Request

Suppose you need to create a user.

The endpoint might be:

POST /users

Create a request model:

@Serializable
data class CreateUserRequest(
    val name: String,
    val email: String
)

Then:

suspend fun createUser(
    request: CreateUserRequest
): User {

    return client
        .post("https://api.example.com/users") {
            contentType(ContentType.Application.Json)
            setBody(request)
        }
        .body()
}

Ktor serializes the Kotlin object into JSON.

---

Example JSON Request

The Kotlin object:

CreateUserRequest(
    name = "John",
    email = "john@example.com"
)

can be sent as JSON similar to:

{
  "name": "John",
  "email": "john@example.com"
}

The exact serialized output depends on your serialization configuration.

---

PUT Request

A PUT request is commonly used to update a resource.

For example:

PUT /users/1

Kotlin:

suspend fun updateUser(
    id: Int,
    request: UpdateUserRequest
): User {

    return client
        .put("https://api.example.com/users/$id") {
            contentType(ContentType.Application.Json)
            setBody(request)
        }
        .body()
}

---

DELETE Request

To delete a resource:

DELETE /users/1

Kotlin:

suspend fun deleteUser(id: Int) {

    client.delete(
        "https://api.example.com/users/$id"
    )
}

---

Adding Query Parameters

APIs frequently require query parameters.

For example:

GET /products?page=1&limit=20

With Ktor:

val response = client.get(
    "https://api.example.com/products"
) {
    parameter("page", 1)
    parameter("limit", 20)
}

This is cleaner than manually building the complete URL.

---

Path Parameters

Sometimes the ID is part of the URL path.

Example:

GET /products/100

Kotlin:

val product =
    client.get(
        "https://api.example.com/products/$id"
    ).body<Product>()

---

HTTP Headers in Ktor

Headers can be added to requests.

For example:

client.get("https://api.example.com/users") {
    header(
        HttpHeaders.Authorization,
        "Bearer $token"
    )
}

Other common headers include:

Content-Type
Accept
Authorization
User-Agent

---

Creating Default Headers

If every request needs the same headers, configure them globally.

Conceptually:

val client = HttpClient {
    defaultRequest {
        header(
            HttpHeaders.Accept,
            ContentType.Application.Json
        )
    }

    install(ContentNegotiation) {
        json()
    }
}

This avoids repeating common configuration in every API call.

---

Ktor Authentication

Many APIs require authentication.

A common approach is:

Login
 ↓
Receive access token
 ↓
Store token
 ↓
Send token with API requests

For example:

Authorization: Bearer <token>

Ktor provides authentication support that can help manage this flow.

The exact implementation depends on your backend authentication system.

---

Bearer Token Authentication

Conceptually, a request looks like:

client.get("/profile") {
    header(
        HttpHeaders.Authorization,
        "Bearer $token"
    )
}

For larger applications, centralize authentication instead of manually adding the token to every API call.

---

Ktor Logging

During development, HTTP logging can be extremely useful.

Ktor provides a logging plugin that can be configured to inspect:

• Requests
• URLs
• Headers
• Responses
• Status codes

Example:

install(Logging) {
    level = LogLevel.INFO
}

Be careful with production logging.

Never log sensitive information such as:

• Passwords
• Access tokens
• Refresh tokens
• Payment information
• Private user data

---

HTTP Status Codes

Your networking layer should understand HTTP status codes.

Common responses include:

200 → OK
201 → Created
204 → No Content
400 → Bad Request
401 → Unauthorized
403 → Forbidden
404 → Not Found
409 → Conflict
422 → Validation Error
429 → Too Many Requests
500 → Server Error

Your application can use these statuses to determine what happened.

---

Ktor Response Validation

Ktor can be configured to validate responses.

For example, you may want non-success responses to result in exceptions.

Conceptually:

install(HttpCallValidator)

The exact configuration depends on your Ktor version and error-handling strategy.

A production application should have a consistent error model rather than allowing random exceptions to reach the UI.

---

Handling API Errors

A common mistake is:

try {
    client.get(...)
} catch (e: Exception) {
    println(e)
}

while treating every error the same.

A better approach is to create a common error model.

For example:

sealed class NetworkResult<out T> {

    data class Success<T>(
        val data: T
    ) : NetworkResult<T>()

    data class Error(
        val message: String
    ) : NetworkResult<Nothing>()
}

Then your repository can expose predictable results.

---

Repository Layer With Ktor

Don’t allow your UI to directly call Ktor.

Avoid:

UI
 ↓
Ktor

Prefer:

UI
 ↓
ViewModel
 ↓
Use Case
 ↓
Repository
 ↓
Ktor

Example:

class UserRepository(
    private val api: UserApi
) {

    suspend fun getUsers(): List<User> {
        return api.getUsers()
    }
}

This keeps Ktor details inside the data layer.

---

KMP API Architecture Example

A scalable project could look like:

shared/
│
└── src/
    │
    ├── commonMain/
    │   │
    │   ├── data/
    │   │   ├── network/
    │   │   │   ├── HttpClientFactory.kt
    │   │   │   ├── UserApi.kt
    │   │   │   └── ProductApi.kt
    │   │   │
    │   │   ├── repository/
    │   │   │   ├── UserRepositoryImpl.kt
    │   │   │   └── ProductRepositoryImpl.kt
    │   │   │
    │   │   └── model/
    │   │
    │   ├── domain/
    │   │   ├── UserRepository.kt
    │   │   └── GetUsersUseCase.kt
    │   │
    │   └── presentation/
    │       └── UserViewModel.kt
    │
    ├── androidMain/
    │   └── network/
    │       └── AndroidHttpEngine.kt
    │
    └── iosMain/
        └── network/
            └── IosHttpEngine.kt

The exact folder structure can vary depending on your project’s architecture.

---

Creating an HTTP Client Factory

A useful pattern is to centralize HTTP client creation.

For example:

fun createHttpClient(): HttpClient {
    return HttpClient {
        install(ContentNegotiation) {
            json()
        }
    }
}

Platform-specific engine setup can then be supplied as needed.

This prevents every API service from creating its own client.

---

Why Should You Reuse One HTTP Client?

Creating a separate client for every request or API service can result in unnecessary configuration and resource usage.

Instead, applications commonly create a configured client and inject it into API services.

HttpClient
    |
    +--- UserApi
    |
    +--- ProductApi
    |
    +--- OrderApi
    |
    +--- ProfileApi

This provides centralized configuration.

---

Dependency Injection With KMP Networking

Dependency injection makes the networking layer easier to test and maintain.

For example:

class ProductRepository(
    private val api: ProductApi
)

Instead of creating ProductApi inside the repository, you provide it from outside.

This allows testing with a fake API implementation.

---

Testing KMP Networking

Networking code should be tested carefully.

You can separate:

Unit Tests
Integration Tests
API Tests

For shared business logic, common tests can validate:

• Repository behavior
• Error handling
• Response mapping
• Business rules

For HTTP behavior, a mock or test server can be useful so that tests don’t depend on a live production API.

---

DTOs vs Domain Models

For production applications, it is often better to separate API response models from domain models.

For example:

@Serializable
data class UserDto(
    val id: Int,
    val name: String,
    val email: String
)

Domain model:

data class User(
    val id: Int,
    val name: String,
    val email: String
)

Then map:

fun UserDto.toDomain(): User {
    return User(
        id = id,
        name = name,
        email = email
    )
}

Architecture:

API JSON
   ↓
DTO
   ↓
Mapper
   ↓
Domain Model
   ↓
Use Case
   ↓
UI

This prevents backend-specific structures from spreading throughout your application.

---

Handling Loading, Success and Error States

A UI usually needs three major states:

Loading
Success
Error

For example:

sealed interface UserUiState {

    data object Loading : UserUiState

    data class Success(
        val users: List<User>
    ) : UserUiState

    data class Error(
        val message: String
    ) : UserUiState
}

Then:

API Request
    ↓
Loading
    ↓
Success / Error

This makes UI behavior predictable.

---

KMP Networking With ViewModel

A simplified ViewModel might look like:

class UserViewModel(
    private val repository: UserRepository
) {

    suspend fun loadUsers() {

        try {
            val users = repository.getUsers()

            // Update UI state
        } catch (e: Exception) {

            // Update error state
        }
    }
}

In a real application, you would typically use structured state management with StateFlow or another suitable mechanism.

---

Ktor and REST APIs

Ktor works well with REST APIs.

For example, a backend might expose:

GET     /products
GET     /products/{id}
POST    /products
PUT     /products/{id}
DELETE  /products/{id}

The shared KMP networking layer can encapsulate these operations.

Example:

class ProductApi(
    private val client: HttpClient
) {

    suspend fun getProducts(): List<Product> =
        client.get("/products").body()

    suspend fun getProduct(id: Int): Product =
        client.get("/products/$id").body()
}

---

Base URL Configuration

Avoid hardcoding your API URL throughout the application.

Bad:

client.get(
    "https://production.example.com/users"
)

in every API function.

Instead, centralize the base URL.

Conceptually:

Development
→ https://dev.example.com

Staging
→ https://staging.example.com

Production
→ https://api.example.com

This makes environment management much easier.

---

API Environment Management

A production application commonly has multiple environments:

Development
Staging
Production

For example:

DEV API
 ↓
Development testing

STAGING API
 ↓
QA/testing

PRODUCTION API
 ↓
Real users

Keep environment configuration separate from your business logic.

---

Handling Timeouts

Network operations can fail because the server takes too long to respond.

Configure appropriate request and connection timeouts.

Conceptually:

install(HttpTimeout) {
    requestTimeoutMillis = 30_000
}

The exact values should depend on the application’s requirements.

Don’t choose extremely long timeouts simply to hide slow API behavior.

---

Retry Logic

Temporary network failures can sometimes be retried.

For example:

Request
 ↓
Network failure
 ↓
Retry
 ↓
Success

However, don’t blindly retry every request.

Be particularly careful with operations that modify data, such as:

POST
PUT
DELETE

because retrying them can potentially create duplicate operations unless the backend supports idempotency.

---

Pagination With Ktor

Large APIs often use pagination.

Example:

GET /products?page=1&limit=20

Kotlin:

suspend fun getProducts(
    page: Int,
    limit: Int
): List<Product> {

    return client
        .get("/products") {
            parameter("page", page)
            parameter("limit", limit)
        }
        .body()
}

Your repository can then control pagination behavior.

---

File Uploads With Ktor

Some applications need to upload:

• Profile images
• Documents
• Product images
• Videos
• Attachments

Ktor supports multipart requests.

Conceptually:

client.submitFormWithBinaryData(
    url = "/upload",
    formData = formData {
        append(
            "file",
            fileBytes,
            Headers.build {
                append(
                    HttpHeaders.ContentType,
                    "image/jpeg"
                )
            }
        )
    }
)

The exact implementation depends on how the file is obtained on each platform.

File-system access is often platform-specific, so the file acquisition layer may belong in androidMain and iosMain.

---

KMP Networking and Secure API Communication

Always use HTTPS for production APIs.

Prefer:

https://api.example.com

instead of:

http://api.example.com

Never hardcode sensitive secrets inside the mobile application.

For example, don’t embed:

Database password
Private API secret
Server master key

in shared Kotlin code.

A mobile application should be treated as a client whose code and embedded values may be inspected.

---

Refresh Token Architecture

For authentication systems that use access and refresh tokens, the flow may look like:

API Request
     ↓
Access Token
     ↓
401 Unauthorized
     ↓
Refresh Token
     ↓
New Access Token
     ↓
Retry Request

This logic should be centralized in the networking/authentication layer rather than duplicated across every API method.

---

KMP Networking Best Practices

1. Keep Ktor Inside the Data Layer

Don’t make UI components responsible for HTTP requests.

Use:

UI
 ↓
ViewModel
 ↓
Repository
 ↓
Ktor

---

2. Reuse the HTTP Client

Create a configured client and inject it into services.

---

3. Centralize Authentication

Don’t manually add authentication headers everywhere if the authentication layer can handle them consistently.

---

4. Separate DTOs and Domain Models

This protects business logic from backend response changes.

---

5. Handle Errors Consistently

Create a predictable error model.

---

6. Use HTTPS

Never send production credentials or sensitive user information over insecure HTTP.

---

7. Don’t Log Secrets

Development logging should never expose passwords or tokens.

---

8. Test Networking

Use test servers or mocks instead of relying entirely on live APIs.

---

9. Keep Platform-Specific Code Small

Put shared API logic in commonMain whenever possible.

Use androidMain and iosMain for platform-specific requirements.

---

Common KMP Networking Mistakes

Mistake 1: Creating API Calls Directly in UI

Avoid:

Screen
 ↓
HTTP request

Use a repository layer.

---

Mistake 2: Duplicating APIs

Avoid:

Android API Service
iOS API Service

when the same API logic can be shared.

Prefer:

Shared API Service

---

Mistake 3: Hardcoding Tokens

Never hardcode real access tokens in source code.

---

Mistake 4: Logging Sensitive Information

Don’t log:

Authorization headers
Passwords
Tokens
Private data

---

Mistake 5: Ignoring Network Failures

A mobile application must handle:

No Internet
Timeout
Server Error
Unauthorized
Invalid Response

---

KMP Networking Architecture Example

A production-oriented architecture could look like:

                    Android UI
                        |
                    iOS UI
                        |
                Shared Presentation
                        |
                    ViewModel
                        |
                    Use Case
                        |
                   Repository
                        |
                  Remote Data Source
                        |
                    API Service
                        |
                  Ktor HttpClient
                        |
              +---------+---------+
              |                   |
          Android Engine      iOS Engine
              |                   |
              +---------+---------+
                        |
                     REST API
                        |
                     Backend

This approach provides a clear separation between application layers.

---

Ktor vs Retrofit for KMP

Developers coming from Android often know Retrofit.

The important difference is that Retrofit was designed primarily around Android/JVM usage, while Ktor Client is designed with multiplatform use cases in mind.

A simplified comparison:

Feature	Ktor Client	Retrofit
Kotlin Multiplatform	Yes	Primarily JVM/Android
Android	Yes	Yes
iOS	Yes	No native iOS KMP client usage
HTTP Client	Yes	Uses HTTP stack underneath
JSON	Yes	Yes
Coroutines	Yes	Yes
Multiplatform focus	Strong	Android/JVM focused
REST APIs	Yes	Yes

For a Kotlin Multiplatform project targeting Android and iOS, Ktor Client is a natural choice for shared HTTP networking.

---

Ktor vs Other Networking Solutions

Ktor isn’t the only networking solution available for Kotlin Multiplatform.

Your decision should consider:

• Target platforms
• Existing architecture
• Team experience
• Serialization requirements
• Authentication needs
• Testing requirements
• Library compatibility
• Long-term maintenance

The best library is the one that fits your application’s requirements rather than simply the one with the most features.

---

Complete KMP API Data Flow

A well-organized application can follow:

User Action
     ↓
UI
     ↓
ViewModel
     ↓
Use Case
     ↓
Repository
     ↓
API Service
     ↓
Ktor Client
     ↓
HTTP Engine
     ↓
Backend
     ↓
JSON Response
     ↓
Ktor Serialization
     ↓
DTO
     ↓
Mapper
     ↓
Domain Model
     ↓
Repository
     ↓
ViewModel
     ↓
UI State
     ↓
UI

This may look complicated initially, but the separation becomes valuable as the application grows.

---

Frequently Asked Questions

What is Ktor Client?

Ktor Client is a Kotlin HTTP client that can be used to make network requests and is suitable for Kotlin Multiplatform applications.

Can Ktor be used with Kotlin Multiplatform?

Yes. Ktor Client supports multiplatform development and can be used to share networking logic between supported targets.

Can I use Ktor for Android and iOS?

Yes. Ktor Client can be used in a KMP project targeting Android and iOS, with platform-appropriate HTTP engines.

Can Ktor parse JSON?

Yes. Ktor can work with JSON serialization through its content negotiation and serialization support.

Is Ktor better than Retrofit?

For a standard Android-only application, both can be viable depending on the project. For Kotlin Multiplatform applications targeting Android and iOS, Ktor Client has a significant advantage because it is designed for multiplatform use.

Can Ktor handle authentication?

Yes. Ktor provides authentication-related functionality, and you can also implement custom token handling depending on your backend.

Can Ktor upload files?

Yes. Ktor supports multipart requests, which can be used for file uploads.

Can I use Ktor with Clean Architecture?

Yes. Ktor fits naturally into the data/network layer of a Clean Architecture-based KMP application.

Should Ktor code be inside commonMain?

Most application-level API and networking logic can be shared in commonMain. Platform-specific HTTP engine configuration may be placed in the relevant platform source sets.

Can KMP share API calls between Android and iOS?

Yes. One of the major benefits of KMP is the ability to share networking and data-layer logic between platforms.

---

Conclusion

Kotlin Multiplatform makes it possible to share a significant amount of networking and API logic between Android and iOS.

Ktor Client is a strong option for this because it provides a Kotlin-first, multiplatform-friendly HTTP client.

A clean KMP networking architecture can look like:

UI
 ↓
ViewModel
 ↓
Use Case
 ↓
Repository
 ↓
API Service
 ↓
Ktor Client
 ↓
Backend

Most common networking functionality can live in:

commonMain

while platform-specific HTTP engine configuration can remain in:

androidMain
iosMain

For production applications, focus on:

• Clean architecture
• Repository patterns
• Shared networking
• JSON serialization
• Consistent error handling
• Authentication
• Secure HTTPS communication
• Proper timeout configuration
• Testing
• DTO-to-domain mapping
• Platform-specific separation

The goal isn’t simply to share as much code as possible. The goal is to create a maintainable networking architecture where Android and iOS can reuse the same API and business logic while still supporting platform-specific requirements.

Once you understand Ktor Client, the next step is to learn how to build a complete KMP REST API architecture with authentication, repositories, dependency injection, error handling, and pagination.