Add one REST endpoint to a KMP app

A concrete recipe: one endpoint, from wire contract to tested repository, in the project's own shape. The architecture behind each step — untrusted DTOs, one shared client, typed errors — is in kmp-data-layer; this skill applies it file by file.

When to use

• Adding a new GET, POST, PUT, PATCH or DELETE call to shared code.
• Adding a method to an existing API service, repository and use case.
• Fixing a freshly added endpoint: parse failures, wrong URL, missing auth header, untested errors.

When not to use

• Designing the data layer, HttpClient, auth refresh or result type from scratch — use kmp-data-layer first.
• Caching the response in a database or syncing offline writes — kmp-data-layer (offline-first) and kmp-room-database.
• DI start-up problems (NoDefinitionFoundException at launch) — kmp-koin-di.

Inputs — get these before writing code

Step 0 — Read the project first

1. Find the closest existing endpoint and copy its shape.

   grep -rln "client.get\|client.post\|HttpClient" --include=*.kt */src/commonMain | head

   Open one complete vertical (API → repository → use case → DI → tests). Note package layout, file names, the toDomain() style, whether use cases exist, and how tests are written.
2. Detect the building blocks — reuse each one, never add a parallel version:

   grep -rnE "sealed (class|interface) [A-Za-z]*(Result|Outcome)" --include=*.kt .    # result type
   grep -rnE "suspend fun <T> [A-Za-z]*(Call|Request)" --include=*.kt .               # error-boundary helper
   grep -rn "named(" --include=*.kt . | grep -i client                                 # client qualifiers
   grep -rnE "DispatcherProvider|MockEngine|class Fake" --include=*.kt . | head -20    # dispatchers, test helpers

3. Check whether files already exist. If OrdersApi exists, add a method; don't create OrdersApi2.

If the project has none of this, set up the data layer with kmp-data-layer first. The examples below use its defaults: ApiResult / DataError, safeApiCall, DispatcherProvider, Koin with named("authenticated"), package com.example.app.

Workflow

Example endpoint: GET orders/{orderId} → one order with line items.

1. Response DTOs — orders/data/remote/dto/OrderDto.kt

@Serializable
data class OrderDto(
    @SerialName("id") val id: String? = null,
    @SerialName("status") val status: String? = null,
    @SerialName("total_minor") val totalMinor: Long? = null,
    @SerialName("currency") val currency: String? = null,
    @SerialName("placed_at") val placedAtEpochMillis: Long? = null,
    @SerialName("items") val items: List<OrderItemDto>? = null,
)

@Serializable
data class OrderItemDto(
    @SerialName("sku") val sku: String? = null,
    @SerialName("name") val name: String? = null,
    @SerialName("quantity") val quantity: Int? = null,
)

Every response field nullable, = null, explicit @SerialName. Enums arrive as String?. Request DTOs (for POST/PUT) may be non-null. Done when the DTO round-trips the sample JSON in a test.

2. Domain model — orders/domain/Order.kt

data class Order(
    val id: String,
    val status: OrderStatus,
    val total: Money,
    val placedAtEpochMillis: Long,
    val items: List<OrderItem>,
)

data class Money(val amountMinor: Long, val currency: String)
data class OrderItem(val sku: String, val name: String, val quantity: Int)
enum class OrderStatus { Pending, Shipped, Delivered, Cancelled, Unknown }

Plain, non-null, no annotations. Money as minor units plus currency, never Double.

3. Mapper — orders/data/OrderMappers.kt

internal fun OrderDto.toDomainOrNull(): Order? {
    val id = id?.takeIf { it.isNotBlank() } ?: return null
    val amount = totalMinor ?: return null            // never default money to 0
    val currency = currency?.takeIf { it.length == 3 } ?: return null
    return Order(
        id = id,
        status = status.toOrderStatus(),
        total = Money(amountMinor = amount, currency = currency.uppercase()),
        placedAtEpochMillis = placedAtEpochMillis ?: 0L,
        items = items.orEmpty().mapNotNull { it.toDomainOrNull() },
    )
}

internal fun OrderItemDto.toDomainOrNull(): OrderItem? {
    val sku = sku?.takeIf { it.isNotBlank() } ?: return null
    val quantity = quantity?.takeIf { it > 0 } ?: return null
    return OrderItem(sku = sku, name = name.orEmpty(), quantity = quantity)
}

private fun String?.toOrderStatus(): OrderStatus = when (this?.lowercase()) {
    "pending" -> OrderStatus.Pending
    "shipped" -> OrderStatus.Shipped
    "delivered" -> OrderStatus.Delivered
    "cancelled" -> OrderStatus.Cancelled
    else -> OrderStatus.Unknown                       // new server values must not crash old apps
}

List each field as required (drop or fail) or cosmetic (fall back). Each rule gets a test.

4. API service — orders/data/remote/OrdersApi.kt

interface OrdersApi {
    suspend fun getOrder(orderId: String): OrderDto
}

internal class KtorOrdersApi(private val client: HttpClient) : OrdersApi {
    override suspend fun getOrder(orderId: String): OrderDto =
        client.get("orders/${orderId.encodeURLPathPart()}").body()
}

• Relative path, no leading / — it resolves against the client's base URL.
• Encode path parameters. encodeURLPathPart() (from io.ktor.http) escapes /, ? and #; raw interpolation lets an id like ../admin or a?b=c change the request.
• No try/catch, no mapping, no headers the shared client already adds.

5. Repository — orders/domain/OrdersRepository.kt + orders/data/OrdersRepositoryImpl.kt

interface OrdersRepository {
    suspend fun getOrder(orderId: String): ApiResult<Order>
}

class OrdersRepositoryImpl(
    private val ordersApi: OrdersApi,
    private val dispatchers: DispatcherProvider,
) : OrdersRepository {

    override suspend fun getOrder(orderId: String): ApiResult<Order> =
        safeApiCall(dispatchers.default) {
            ordersApi.getOrder(orderId).toDomainOrNull()
                ?: throw SerializationException("Order response is missing required fields")
        }
}

The error boundary maps HTTP status, transport and parse failures to DataError and rethrows cancellation. An order missing required fields becomes DataError.Serialization, not a crash and not a half-empty screen.

6. Use case — only if the project uses them

// orders/domain/GetOrderUseCase.kt
class GetOrderUseCase(private val ordersRepository: OrdersRepository) {
    suspend operator fun invoke(orderId: String): ApiResult<Order> {
        if (orderId.isBlank()) return ApiResult.Failure(DataError.Validation(serverMessage = null))
        return ordersRepository.getOrder(orderId)
    }
}

If the project's ViewModels call repositories directly, skip this file — a pass-through use case adds a layer and tests nothing.

7. DI — orders/di/OrdersModule.kt

val ordersModule = module {
    single<OrdersApi> { KtorOrdersApi(client = get(named("authenticated"))) }
    single<OrdersRepository> { OrdersRepositoryImpl(ordersApi = get(), dispatchers = get()) }
    factoryOf(::GetOrderUseCase)
}

Add ordersModule to the app's module list (or the feature aggregator's includes(...)). Use the plain client for endpoints that must not carry a token. Done when the DI verification test passes (see kmp-koin-di) or the app starts and resolves the screen's ViewModel.

8. Tests — commonTest/.../orders/

Write these four, using the templates in references/test-templates.md:

Name tests should_<expected>_when_<condition> unless the project uses another convention.

9. Run the checks in Verify.

Variations

Quick reference — files for GET orders/{orderId}

Verify

Report each check as PASS, FAIL or NOT RUN (with the reason). Do not report a check you did not run. Read settings.gradle.kts for the real module name; the Android host-test task is testDebugUnitTest with com.android.library and testAndroidHostTest with com.android.kotlin.multiplatform.library.

./gradlew :shared:testDebugUnitTest --tests "com.example.app.orders.*"     # fast JVM loop
./gradlew :shared:iosSimulatorArm64Test --tests "com.example.app.orders.*" # Kotlin/Native
./gradlew :shared:allTests                                                 # everything before you finish
./gradlew :composeApp:assembleDebug                                        # app still builds

Static checks (adjust shared/src/commonMain to the module you changed; review every hit):

grep -rnE "val [A-Za-z0-9_]+: [^?=]+(,|$)" --include=*Dto.kt shared/src/commonMain           # non-null DTO fields
grep -rnE 'client\.(get|post|put|patch|delete)\("[^"]*\$' --include=*.kt shared/src/commonMain | grep -v encodeURLPathPart   # unencoded path params
grep -rn "HttpClient(" --include=*.kt shared/src/commonMain                                   # clients outside the network module

Common mistakes

Related skills

• kmp-data-layer — the architecture these steps implement: client, DTO rules, ApiResult, offline-first.
• kmp-koin-di — module registration and the DI verification test.
• kmp-room-database — caching the response locally.
• Ktor client testing: https://ktor.io/docs/client-testing.html
• Ktor requests (parameters, bodies, forms): https://ktor.io/docs/client-requests.html