REST APIレスポンスをKotlin Data Classでモデリングする

KotlinでのREST APIレスポンスモデリング

ほとんどのREST APIはデータをステータス、データ、ページネーション、エラーフィールドを含む標準エンベロープでラップします。これをKotlinに変換するには、複数のdata classの慎重な構造化が必要です。

典型的なAPIレスポンスJSON

{
  "status": "success",
  "data": {
    "users": [
      { "id": 1, "name": "Alice", "email": "alice@example.com" },
      { "id": 2, "name": "Bob", "email": "bob@example.com" }
    ]
  },
  "pagination": {
    "currentPage": 1,
    "perPage": 20,
    "total": 152,
    "totalPages": 8
  }
}

生成されるKotlin

@Serializable
data class ApiResponse(
    val status: String,
    val data: UserListData,
    val pagination: Pagination? = null
)

@Serializable
data class UserListData(
    val users: List<User>
)

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

@Serializable
data class Pagination(
    val currentPage: Int,
    val perPage: Int,
    val total: Int,
    val totalPages: Int
)

エラーレスポンスの処理

APIはエラー時に異なる構造を返します：

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

@Serializable
data class ApiErrorResponse(
    val status: String,
    val error: ApiError
)

@Serializable
data class ApiError(
    val code: String,
    val message: String
)

Sealed Classによる統一レスポンス

sealed class ApiResult<out T> {
    data class Success<T>(
        val data: T,
        val pagination: Pagination? = null
    ) : ApiResult<T>()

    data class Failure(
        val error: ApiError
    ) : ApiResult<Nothing>()
}

Retrofit統合

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int
    ): ApiResponse
}

Ktorクライアント統合

val response: ApiResponse = client.get("https://api.example.com/users") {
    parameter("page", 1)
}.body()

Retrofit（kotlinx.serializationコンバーター使用）とKtorの両方が、JSONをKotlin data classに自動的にデシリアライズします。