KotlinでGraphQL APIを呼び出す方法を解説！初心者にもわかるAPI連携の基本

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

生徒

「KotlinでGraphQLって使えますか？REST APIしか使ったことなくて、ちょっと難しそうです…」

先生

「もちろんKotlinでもGraphQL APIを使えるよ！GraphQLは必要なデータだけをリクエストできる新しいスタイルのAPIなんだ。基本からやってみようか。」

生徒

「お願いします！JSONとかPOSTとか出てくると混乱しちゃいます…」

先生

「ゆっくり丁寧に解説するから安心して。GraphQLの基本からKotlinでの実装方法まで、一緒にやってみよう！」

1. GraphQL APIとは？

GraphQL（グラフキューエル）とは、Facebookが開発したAPIの設計方式で、必要なデータだけを指定して取得できる特徴があります。

たとえば「ユーザーの名前と年齢だけが欲しい」ときに、それだけを明確にリクエストできます。これは「REST API」と違って、柔軟性の高い通信が可能になります。

2. GraphQLのリクエスト構造

GraphQLでは、POSTリクエストを使って「クエリ（query）」を送信します。内容はJSON形式で、次のようになります：


{
  "query": "{ user { name age } }"
}

このように、取得したいフィールド（name、age）を明示的に指定します。

3. KotlinでGraphQL APIを使う準備

GraphQL APIを呼び出すには、HTTPリクエストが送れるライブラリが必要です。今回はシンプルにOkHttpを使います。

まずはGradleに以下を追加しましょう：


dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
}

4. KotlinでGraphQL APIを呼び出す基本コード

次に、KotlinでGraphQL APIにPOSTリクエストを送信して、レスポンスを取得する基本コードを紹介します。


import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

fun main() {
    val client = OkHttpClient()

    val query = """
        {
          "query": "{ user { name age } }"
        }
    """.trimIndent()

    val mediaType = "application/json; charset=utf-8".toMediaType()
    val requestBody = query.toRequestBody(mediaType)

    val request = Request.Builder()
        .url("https://example.com/graphql")
        .post(requestBody)
        .build()

    client.newCall(request).execute().use { response ->
        println(response.body?.string())
    }
}

このコードでは、JSONの文字列をリクエストボディとしてPOST送信し、サーバーからのレスポンスを受け取っています。

5. 実行結果の例

正しく通信できた場合、次のような結果が返ってきます（内容はダミーです）：


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

6. POSTメソッドとJSONについて

GraphQL APIを使うには、POSTメソッドという形式でリクエストを送ります。これは「サーバーにデータを渡して返事をもらう」方法です。

リクエストの中身はJSON形式で記述します。JSON（ジェイソン）は、データを「鍵と値」のペアで表現するテキスト形式で、人にもコンピュータにも読みやすいのが特徴です。

7. よくある失敗とその対処法

GraphQL APIを呼び出すときにありがちなミスには、次のようなものがあります：

URLが間違っている（404エラー）
クエリの文法ミス（GraphQL構文エラー）
JSONの形式が崩れている（パースエラー）

そういったときは、println(response.body?.string())で中身を確認し、何が原因かを読み取るようにしましょう。

8. KotlinでGraphQLを使うメリットとは？

KotlinでGraphQLを使うと、必要なデータだけを取得できるため、無駄な通信が減り、効率的なネットワーク処理が可能になります。

特にモバイルアプリでは通信量を減らすことがとても大切なので、GraphQLはおすすめの選択肢です。

9. 複雑なクエリもKotlinから送信できる？

もちろんできます。GraphQLでは「ネストされたデータ（入れ子構造）」や「引数付きのクエリ」なども使えます。

たとえば次のように、ユーザーIDを指定して情報を取得することも可能です：


{
  "query": "{ user(id: 1) { name email } }"
}

Kotlinではこの文字列をリクエストボディにそのまま送るだけなので、使い方もシンプルです。