KotlinでAPIにヘッダーやクエリパラメータを設定する方法をやさしく解説！初心者向けネットワーク通信ガイド

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

生徒

「KotlinでWebのAPIにアクセスする方法ってありますか？」

先生

「ありますよ。Kotlinでは、インターネット上のAPIとやり取りするための方法がいくつかあります。特に、ヘッダーやクエリパラメータを使うと、もっと便利になりますよ。」

生徒

「ヘッダーとかクエリパラメータって、何ですか？」

先生

「とてもいい質問ですね。難しそうに見えるけど、実はわかりやすく説明できるんですよ。さっそく見ていきましょう！」

1. APIリクエストとは？

API（エーピーアイ）とは、アプリやプログラムがインターネットを通じて、他のサービスとやり取りするための「約束事」です。例えば、天気予報を表示するアプリでは、天気APIから情報を取得します。

このとき、APIに情報をリクエスト（お願い）する必要があります。これを「APIリクエスト」と呼びます。

2. ヘッダーとクエリパラメータとは？

APIにリクエストを送るとき、「ヘッダー」や「クエリパラメータ」といった情報を一緒に渡すことがあります。

ヘッダー：手紙でいうと「封筒の外側の宛名」みたいなもの。誰が送っているか、どんな形式かなどを伝えます。
クエリパラメータ：URLの後ろに「?」で付ける情報です。例えば「?id=123&name=tanaka」のように、欲しいデータを指定できます。

3. KotlinでHTTPリクエストを送るライブラリ「OkHttp」とは？

KotlinでAPI通信をするために使われる人気のライブラリがOkHttp（オーケーエイチティーティーピー）です。

これは、簡単にネットワークリクエストを送れるツールで、初心者にもわかりやすいコードで書けるのが特長です。

4. ヘッダーやクエリパラメータを使ったサンプルコード

それでは、実際にKotlinでAPIにアクセスし、ヘッダーとクエリパラメータを設定してみましょう。


import okhttp3.OkHttpClient
import okhttp3.Request

fun main() {
    val client = OkHttpClient()

    // クエリパラメータ付きのURL
    val url = "https://api.example.com/data?userId=123&lang=ja"

    // リクエストの作成（ヘッダーも追加）
    val request = Request.Builder()
        .url(url)
        .addHeader("Authorization", "Bearer your_token_here")
        .addHeader("Accept", "application/json")
        .build()

    // リクエストを送信
    client.newCall(request).execute().use { response ->
        println("HTTPステータスコード: ${'$'}{response.code}")
        println("レスポンス本文: ${'$'}{response.body?.string()}")
    }
}

このコードでは、URLに「userId」と「lang」というクエリパラメータを付けています。また、「Authorization」や「Accept」といったヘッダーも設定しています。

5. 具体的な使い道とよくある用途

ヘッダーやクエリパラメータは、次のような場面でよく使われます。

ログインしている人の情報を送るとき（ヘッダーでトークンを送る）
検索やフィルター条件を指定したいとき（クエリパラメータ）
言語や地域設定を伝えるとき

つまり、APIをより柔軟に使うために欠かせない仕組みなのです。

6. クエリパラメータの組み立て方の工夫

URLの文字列にクエリパラメータを自分で追加するのが難しい場合は、次のようにHttpUrl.Builderを使う方法もあります。


import okhttp3.HttpUrl
import okhttp3.OkHttpClient
import okhttp3.Request

fun main() {
    val client = OkHttpClient()

    // HttpUrlを使って安全にURLを構築
    val url = HttpUrl.Builder()
        .scheme("https")
        .host("api.example.com")
        .addPathSegment("data")
        .addQueryParameter("userId", "123")
        .addQueryParameter("lang", "ja")
        .build()

    val request = Request.Builder()
        .url(url)
        .addHeader("Authorization", "Bearer your_token_here")
        .addHeader("Accept", "application/json")
        .build()

    client.newCall(request).execute().use { response ->
        println("HTTPステータスコード: ${'$'}{response.code}")
        println("レスポンス本文: ${'$'}{response.body?.string()}")
    }
}

この方法だと、パラメータの追加ミスや記号のエスケープ（特殊文字の処理）も自動でやってくれるので安心です。

7. 実行結果のイメージ

実行すると、以下のような結果が表示されます。


HTTPステータスコード: 200
レスポンス本文: {"message":"データを取得しました","data":[...]}

8. APIの通信エラー時の注意点

APIと通信する際、ネットワークの問題や認証エラーが起こることがあります。そのため、try-catchで例外処理を書くとより安全です。

また、ステータスコードが401（未認証）や404（見つからない）などの場合もあるため、必ずresponse.codeでチェックするのが基本です。

9. ヘッダーとクエリパラメータを活用してAPIを使いこなそう！

今回は、KotlinでAPIリクエストを送る方法、そしてヘッダーやクエリパラメータの使い方について学びました。

ネットワークを通じたAPI連携は、天気情報の取得、ユーザー情報の送信、ニュース一覧の表示など、さまざまなアプリ開発に欠かせない技術です。

最初は難しく感じるかもしれませんが、ひとつひとつ覚えていけば、しっかり使いこなせるようになりますよ。