Why Sealed Interfaces Are Kotlin’s Hidden Gem for API Design

As an Android developer, I’ve wrestled with messy API response handling more times than I’d like to admit. Parsing JSON, dealing with error states, and keeping code maintainable can feel like a never-ending battle. Enter Kotlin’s sealed interfaces — a feature that’s quietly become one of my favorite tools for designing clean, type-safe, and expressive network layers. Introduced in Kotlin 1.5, sealed interfaces combine the flexibility of interfaces with the control of sealed classes, making them perfect for modeling complex API responses. In this post, I’ll walk you through why sealed interfaces are a game-changer for Android developers, with practical examples and tips to level up your API design.

For non-member readers: click me

What Are Sealed Interfaces?

Sealed interfaces are a Kotlin feature that restricts the types implementing an interface to a predefined set, much like sealed classes. Unlike regular interfaces, which can be implemented by any class, sealed interfaces ensure that all implementations are known at compile time. This makes them ideal for modeling finite, well-defined states — like API responses with success, error, or loading states.

Here’s a quick example:

sealed interface ApiResult<out T> {
    data class Success<T>(val data: T) : ApiResult<T>
    data class Error(val message: String, val code: Int? = null) : ApiResult<Nothing>
    object Loading : ApiResult<Nothing>
}

In this case, ApiResult can only be Success, Error, or Loading. The compiler enforces this, so you can’t accidentally introduce unexpected states.

Why Use Sealed Interfaces for API Design?

Sealed interfaces shine in Android development for several reasons:

• Type Safety: The compiler ensures you handle all possible cases, reducing runtime errors.
• Conciseness: They combine the flexibility of interfaces with the structure of sealed classes, cutting boilerplate.
• Expressiveness: They model complex states clearly, making code easier to reason about.
• Extensibility: You can extend sealed interfaces across modules or libraries, unlike sealed classes, which are limited to the same file.

Let’s dive into practical use cases to see how they solve real-world problems.

Use Case 1: Modeling API Responses

When building a network layer, API responses typically have multiple states: success with data, errors with details, or a loading state. Sealed interfaces make this a breeze.

Here’s an example using Retrofit and coroutines:

sealed interface UserResult {
    data class Success(val user: User) : UserResult
    data class Error(val message: String, val code: Int? = null) : UserResult
    object Loading : UserResult
}

interface UserApi {
    @GET("user/{id}")
    suspend fun getUser(@Path("id") userId: String): Response<User>
}

class UserRepository(private val api: UserApi) {
    suspend fun fetchUser(userId: String): UserResult = withContext(Dispatchers.IO) {
        try {
            val response = api.getUser(userId)
            if (response.isSuccessful) {
                response.body()?.let { UserResult.Success(it) } ?: UserResult.Error("No user data")
            } else {
                UserResult.Error("Failed: ${response.message()}", response.code())
            }
        } catch (e: Exception) {
            UserResult.Error("Network error: ${e.message}")
        }
    }
}

In your ViewModel:

class UserViewModel(private val repository: UserRepository) : ViewModel() {
    private val _userState = MutableLiveData<UserResult>()
    val userState: LiveData<UserResult> = _userState

fun fetchUser(userId: String) {
        _userState.value = UserResult.Loading
        viewModelScope.launch {
            _userState.value = repository.fetchUser(userId)
        }
    }
}

In your Activity/Fragment:

viewModel.userState.observe(this) { result ->
    when (result) {
        is UserResult.Success -> displayUser(result.user)
        is UserResult.Error -> showError(result.message)
        UserResult.Loading -> showLoading()
    }
}

Why It’s Great:

• The when expression is exhaustive, so the compiler ensures you handle all cases.
• The sealed interface keeps the code concise yet expressive.
• You can easily add new states (e.g., Unauthorized) without breaking existing code.

Use Case 2: Handling Complex Nested States

Sometimes, APIs return nested or conditional data. For example, a user profile might include optional subscription details. Sealed interfaces can model this elegantly.

sealed interface UserProfile {
    val userId: String

data class Basic(override val userId: String, val name: String) : UserProfile
    data class Premium(
        override val userId: String,
        val name: String,
        val subscription: Subscription
    ) : UserProfile

data class Subscription(val plan: String, val expiresAt: Long)
}

Usage in a ViewModel:

class ProfileViewModel(private val repository: UserRepository) : ViewModel() {
    private val _profile = MutableLiveData<UserProfile>()
    val profile: LiveData<UserProfile> = _profile

fun fetchProfile(userId: String) {
        viewModelScope.launch {
            val result = repository.fetchUser(userId)
            _profile.value = when (result) {
                is UserResult.Success -> {
                    if (result.user.hasSubscription) {
                        UserProfile.Premium(
                            userId = result.user.id,
                            name = result.user.name,
                            subscription = UserProfile.Subscription(
                                plan = result.user.plan,
                                expiresAt = result.user.expiresAt
                            )
                        )
                    } else {
                        UserProfile.Basic(userId = result.user.id, name = result.user.name)
                    }
                }
                is UserResult.Error -> UserProfile.Basic(userId = userId, name = "Unknown")
                UserResult.Loading -> return@launch // Wait for data
            }
        }
    }
}

Why It’s Great:

• Sealed interfaces let you model hierarchical data (e.g., Basic vs. Premium) with shared properties (userId).
• The compiler ensures you handle all profile types, preventing bugs.
• It’s easy to extend with new profile types later.

Use Case 3: Cross-Module Extensibility

Unlike sealed classes, which must define all subclasses in the same file, sealed interfaces allow implementations across different modules. This is a lifesaver for large Android projects with modular architectures.

Imagine a shared network module and a feature module:

// In :network module
sealed interface ApiResponse<out T> {
    data class Success<T>(val data: T) : ApiResponse<T>
    data class Error(val message: String) : ApiResponse<Nothing>
}

// In :feature module
data class FeatureSpecificError(val details: String) : ApiResponse<Nothing>

You can use this in a feature-specific ViewModel:

class FeatureViewModel : ViewModel() {
    private val _state = MutableLiveData<ApiResponse<String>>()
    val state: LiveData<ApiResponse<String>> = _state

fun doSomething() {
        viewModelScope.launch {
            _state.value = try {
                val data = fetchData()
                ApiResponse.Success(data)
            } catch (e: FeatureException) {
                FeatureSpecificError(e.details)
            }
        }
    }
}

Why It’s Great:

• Sealed interfaces allow you to extend response types in feature modules without modifying the core network module.
• You maintain type safety across modules, keeping your codebase modular and maintainable.

Best Practices for Sealed Interfaces

• Keep It Simple: Use sealed interfaces for finite states (e.g., API responses, UI states). For open-ended hierarchies, regular interfaces are better.
• Leverage Exhaustive When: Always use when expressions to handle all cases, letting the compiler catch missing branches.
• Combine with Coroutines: Pair sealed interfaces with viewModelScope for lifecycle-aware API handling.
• Use Descriptive Names: Name states clearly (e.g., Success, Error) to make code self-documenting.
• Test Edge Cases: Write unit tests to verify all states, especially error cases.

Here’s a quick test example using kotlinx-coroutines-test:

@Test
fun `fetchUser handles all states`() = runBlockingTest {
    val repository = mock<UserRepository>()
    val viewModel = UserViewModel(repository)
    coEvery { repository.fetchUser("123") } returns UserResult.Error("Failed", 404)

viewModel.fetchUser("123")
    assertEquals(UserResult.Error("Failed", 404), viewModel.userState.value)
}

Gotchas to Watch Out For

• Overcomplicating Hierarchies: Don’t overuse sealed interfaces for simple cases; a data class or enum might suffice.
• Forgetting Cancellation: When using coroutines, ensure your suspend functions are cancellation-aware to avoid running after ViewModel cleanup.
• Performance Overhead: While sealed interfaces are lightweight, excessive nesting can make when expressions harder to read. Keep hierarchies shallow.

Why Sealed Interfaces Changed My Approach

Before discovering sealed interfaces, I relied heavily on sealed classes or plain data classes with enums for API responses. Sealed classes worked but felt restrictive when I needed to share types across modules. Enums were too rigid for complex data. Sealed interfaces struck the perfect balance: type safety, flexibility, and extensibility. In one project, switching to sealed interfaces cut my error-handling boilerplate by 30% and made my code easier to reason about. Plus, the compiler’s exhaustive checks saved me from countless bugs.

Conclusion

Sealed interfaces are Kotlin’s hidden gem for Android developers building robust network layers. They bring type safety, conciseness, and extensibility to API design, making it easier to handle complex responses without the usual mess. Whether you’re modeling simple success/error states or intricate nested data, sealed interfaces keep your code clean and maintainable. Next time you’re designing an API layer, give them a try — I bet you’ll wonder how you lived without them.

What’s your favorite way to handle API responses in Android? Share your thoughts below — I’m curious to hear your approach!