KotlinのAPIレスポンスをモデルクラスにマッピングする方法を徹底解説！初心者でも安心の入門ガイド

先生と生徒の会話形式で理解しよう

生徒

「Kotlinでインターネットからデータを取ってくるAPIってよく聞くけど、それをどうやって使いやすい形に変えるの？」

先生

「APIから送られてくるデータはJSONという形式で来ることが多いんだけど、それをKotlinのモデルクラスにマッピングすると扱いやすくなるんだ。」

生徒

「モデルクラスって何ですか？」

先生

「簡単に言うと、データを入れるための型付きの箱みたいなものだよ。じゃあ実際にどんな風に使うのか、ゆっくり説明していくね。」

1. APIレスポンスとモデルクラスとは？

Kotlin（ことりん）でAPI（エーピーアイ）と連携するとき、サーバーから受け取るデータはほとんどの場合「JSON（ジェイソン）」形式で送られてきます。これは見た目がちょっとコードに似たテキストの形式です。

例えば、以下のようなJSONがあります：


{
    "name": "Taro",
    "age": 25
}

このJSONの内容をKotlinで使いやすくするために、「モデルクラス」を作って、そこに自動的にデータを入れてくれる仕組みを使います。これを「マッピング」と呼びます。

2. モデルクラスを作ってみよう

Kotlinでモデルクラスを作るときは、「data class（データクラス）」という便利な仕組みを使います。

先ほどのJSONに対応するモデルクラスは、次のようになります：


data class User(
    val name: String,
    val age: Int
)

このUserクラスは、nameが文字列（String）、ageが整数（Int）になっています。JSONのキーと一致するようにプロパティの名前をつけることが重要です。

3. JSONをモデルクラスに変換するには？

Kotlinでは、JSONをモデルクラスに変換（パース）するために「ライブラリ」という道具を使います。代表的なものにGsonやMoshiなどがあります。ここでは、Googleが作ったGsonを使って説明します。

まず、Gsonライブラリをプロジェクトに追加します。Gradleファイルに次のように書きます：


dependencies {
    implementation("com.google.code.gson:gson:2.10.1")
}

次に、実際にJSON文字列をUserクラスに変換してみましょう。


import com.google.gson.Gson

fun main() {
    val json = """{ "name": "Taro", "age": 25 }"""
    val gson = Gson()
    val user = gson.fromJson(json, User::class.java)

    println("名前: ${user.name}, 年齢: ${user.age}")
}

このコードでは、fromJsonという関数を使ってJSONをUserクラスに変換しています。

4. 出力結果を確認しよう

上記のコードを実行すると、次のように出力されます。


名前: Taro, 年齢: 25

このように、サーバーから送られてきたJSON形式のデータが、Kotlinのモデルクラスに自動で変換されて使いやすくなります。

5. モデルクラスの注意点と豆知識

モデルクラスのプロパティ名は、JSONのキーと完全に一致していないと正しくマッピングできません。たとえばJSONが"user_name"なのにモデルクラスがuserNameだとエラーになることがあります。

そんなときは、Gsonのアノテーション（特別な指定）を使って対応します：


import com.google.gson.annotations.SerializedName

data class User(
    @SerializedName("user_name") val userName: String,
    val age: Int
)

@SerializedNameを使えば、JSONの名前とKotlinのプロパティ名が違っていてもちゃんとマッピングできます。

6. KotlinでAPIを扱うメリットとは？

KotlinでAPIを使ってサーバーと通信し、そのレスポンスをモデルクラスにマッピングすることで、データの取り扱いが非常に簡単になります。

手作業で1つ1つデータを取り出す必要がなくなり、プログラムの読みやすさや安全性もアップします。

実際のAndroidアプリやWebシステムでも、この方法は非常によく使われています。

7. もっと実践的な使い方は？

今回の例は簡単なものでしたが、実際には「配列（リスト）」や「入れ子のJSON（ネスト）」などもよく出てきます。そういった場合でも、モデルクラスを工夫することで、複雑なデータ構造を扱えるようになります。

例えば、複数のユーザーを受け取る場合はこうです：


[
    { "name": "Taro", "age": 25 },
    { "name": "Hanako", "age": 30 }
]

この場合は、List<User>の形で受け取ればOKです。


val json = """[{"name":"Taro","age":25},{"name":"Hanako","age":30}]"""
val users: List<User> = gson.fromJson(json, Array<User>::class.java).toList()