api-and-interface-design

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()
}

1. 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

1. 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)
}