API and Interface Design

Overview

Hyrum's Law: "With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody." Design interfaces — Repository contracts, UseCase signatures, Retrofit services, Room DAOs — as deliberate contracts. Everything observable becomes a dependency.

When to Use

• Defining a new Repository interface
• Creating Retrofit API service interfaces
• Designing Room DAOs
• Defining ViewModel ↔ UI contracts (UiState, Events)
• Changing any public interface in a shared module
• Designing inter-module contracts in multi-module projects
• Sending state-changing requests that can be retried (payments, orders, messages, uploads)

Skip when: Modifying internal (private) implementation details.

Core Process

Step 1: Contract-First Design

1. Define the interface before implementing:

// Repository contract (in :core:domain)
interface TaskRepository {
    fun getTasks(): Flow<List<Task>>
    fun getTaskById(taskId: String): Flow<Task?>
    suspend fun createTask(title: String, description: String?): Task
    suspend fun updateTask(task: Task)
    suspend fun deleteTask(taskId: String)
    suspend fun syncWithRemote()
}

2. Design principles:
   • Return Flow for observable data (not suspend for single reads)
   • Use suspend for one-shot operations
   • Accept domain types, not framework types (no Entity in interfaces)
   • Throw domain-specific exceptions, not framework exceptions

Step 2: Retrofit Interfaces

3. Define clean API contracts:

interface TaskApi {
    @GET("tasks")
    suspend fun getTasks(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20,
    ): TaskListResponse

    @GET("tasks/{id}")
    suspend fun getTask(@Path("id") taskId: String): TaskResponse

    @POST("tasks")
    suspend fun createTask(@Body request: CreateTaskRequest): TaskResponse

    @PUT("tasks/{id}")
    suspend fun updateTask(
        @Path("id") taskId: String,
        @Body request: UpdateTaskRequest,
    ): TaskResponse

    @DELETE("tasks/{id}")
    suspend fun deleteTask(@Path("id") taskId: String)
}

4. API contract rules:
   • Use @Serializable data classes for request/response bodies (Kotlin Serialization)
   • Separate request and response models (even if fields overlap)
   • Use sealed class for polymorphic responses
   • Never expose Retrofit internals (no Response<T> in Repository interface)

Step 3: Data Models and Sealed Types

5. Use the type system to make illegal states unrepresentable:

// BAD: stringly-typed status
data class Task(
    val id: String,
    val title: String,
    val status: String, // "pending", "in_progress", "completed" — typos possible
)

// GOOD: sealed type
data class Task(
    val id: String,
    val title: String,
    val status: TaskStatus,
)

sealed interface TaskStatus {
    data object Pending : TaskStatus
    data object InProgress : TaskStatus
    data class Completed(val completedAt: Instant) : TaskStatus
}

6. Use value classes for type safety:

@JvmInline
value class TaskId(val value: String)

@JvmInline
value class UserId(val value: String)

// Prevents accidentally passing a UserId where a TaskId is expected
suspend fun getTask(taskId: TaskId): Task

Step 4: Error Handling Strategy

7. Define domain-specific errors:

sealed interface DataError {
    data class Network(val cause: Throwable) : DataError
    data class NotFound(val id: String) : DataError
    data class Validation(val message: String) : DataError
    data object Unauthorized : DataError
    data class Unknown(val cause: Throwable) : DataError
}

// Use Result type for operations that can fail
suspend fun createTask(title: String): Result<Task>

// Or define a custom Result type
sealed interface DataResult<out T> {
    data class Success<T>(val data: T) : DataResult<T>
    data class Error(val error: DataError) : DataResult<Nothing>
}

8. Error handling rules:
   • Catch specific exceptions, not generic Exception
   • Map framework exceptions to domain errors at the boundary
   • Never swallow errors silently
   • Provide actionable error messages for the UI

Step 5: Backward Compatibility

9. Extend, don't modify:

// Version 1
interface TaskRepository {
    fun getTasks(): Flow<List<Task>>
    suspend fun createTask(title: String): Task
}

// Version 2: ADD new methods, don't change existing signatures
interface TaskRepository {
    fun getTasks(): Flow<List<Task>>
    suspend fun createTask(title: String): Task

    // New: added with default implementation for backward compatibility
    fun getTasksByStatus(status: TaskStatus): Flow<List<Task>> =
        getTasks().map { tasks -> tasks.filter { it.status == status } }
}

10. When breaking changes are necessary:
    • Deprecate with @Deprecated and replacement guidance
    • Provide a migration period
    • Update all callers in the same PR
    • See deprecation-and-migration for the full process

Step 6: Naming Conventions

Step 7: Validation at Boundaries

11. Validate at system boundaries, trust internally:

// At the API boundary (Retrofit interceptor or repository)
class TaskRepositoryImpl @Inject constructor(
    private val api: TaskApi,
    private val dao: TaskDao,
) : TaskRepository {

    override suspend fun createTask(title: String, description: String?): Task {
        // Validate at boundary
        require(title.isNotBlank()) { "Task title must not be blank" }
        require(title.length <= 200) { "Task title must not exceed 200 characters" }

        val entity = TaskEntity(
            id = UUID.randomUUID().toString(),
            title = title.trim(),
            description = description?.trim(),
        )
        dao.upsert(entity)
        return entity.toDomain()
    }
}

Step 8: Idempotency Keys for Retried Writes

12. Assume every write is sent more than once. On Android, duplicates come from OkHttp's retryOnConnectionFailure, caller retry loops, WorkManager retries with backoff, double-taps, and process death between sending a request and persisting the response. A timeout means unknown, not failed — the server may already have applied it. For non-idempotent writes (POST that charges, orders, sends), attach an Idempotency-Key.

Key the intent, not the attempt. Generate a UUID once when the user commits the action, persist it with the pending operation (Room outbox row or WorkManager inputData), and reuse it on every retry — including after process death:

@Entity data class PendingOrder(@PrimaryKey val idempotencyKey: String, val cartId: String, val payload: String)

suspend fun placeOrder(cart: Cart) {                       // runs once per user intent
    val op = PendingOrder(UUID.randomUUID().toString(), cart.id, json.encodeToString(cart.toRequest()))
    outboxDao.insert(op)                                   // key survives process death
    workManager.enqueue(OneTimeWorkRequestBuilder<SubmitOrderWorker>()
        .setInputData(workDataOf("key" to op.idempotencyKey)).build())
}

interface OrderApi {
    @POST("orders")
    suspend fun createOrder(@Header("Idempotency-Key") key: String, @Body body: CreateOrderRequest): OrderResponse
}

// In SubmitOrderWorker.doWork(): same key on every attempt
val key = inputData.getString("key") ?: return Result.failure()
val op = outboxDao.get(key) ?: return Result.success()     // already submitted
return try {
    api.createOrder(op.idempotencyKey, json.decodeFromString(op.payload))
    outboxDao.delete(op)
    Result.success()
} catch (e: IOException) {
    Result.retry()                                         // outcome unknown: retry with the same key
} catch (e: HttpException) {
    if (e.code() == 409) Result.retry() else Result.failure() // 409 = still in flight (check your server's contract)
}

• Never generate the key inside an OkHttp interceptor, the Retrofit call, or doWork() — that layer runs once per attempt. If you prefer an interceptor over @Header, pass the stored key via a Retrofit @Tag and read it with request.tag().
• Don't derive the key from content ("$userId:$amount") — two legitimate identical orders would collapse into one.

Know the server contract (usually another team's): it stores key + request fingerprint + response, replays the stored response for a repeat, rejects the same key with a different body (422, sometimes 409), returns 409 while the first attempt is still in flight, and expires keys after a window. Client consequences: treat a replayed response as success, retry an in-flight 409 with backoff, treat a body-mismatch error as a client bug (never "fix" it with a new key), and keep the outbox retry horizon shorter than the server's key expiry.

Common Rationalizations

Red Flags

• Room entities exposed to UI layer
• Retrofit Response<T> returned from Repository
• Generic String where sealed type or enum is appropriate
• No validation at system boundaries
• Breaking interface changes without deprecation
• Any or Object in public interfaces
• Inconsistent naming across layers
• Non-idempotent POST (payment, order, message) retried without an Idempotency-Key
• UUID.randomUUID() for the key inside an interceptor, API call, or doWork()
• Idempotency key held only in memory or a ViewModel, not persisted with the pending operation
• A 409/422 on a keyed request "handled" by retrying with a new key

Verification

• Interfaces designed before implementation (contract-first)
• Domain types used at interface boundaries (not framework types)
• Sealed types used for finite state sets
• Error handling uses domain-specific error types
• Validation at system boundaries, trust internally
• Naming follows project conventions
• Backward compatibility maintained (or breaking change documented)
• Tests verify interface contracts
• Every retryable state-changing request sends an Idempotency-Key, or is documented as unsafe to retry
• Key is generated once per user intent and persisted with the pending operation (test: kill the process mid-request, the retry sends the same key)
• 409/422 and replayed responses are handled per the server contract, and the client retry horizon is shorter than server key expiry