[Rustのはじめ方] Part33: JSON APIとの連携とシリアライズ

現代の多くのアプリケーションは、外部のWeb APIと連携してデータを取得したり、操作したりします。これらのAPIの多くは、データ交換形式としてJSON (JavaScript Object Notation) を採用しています。

RustでJSON APIと連携するには、主に以下の2つの機能が必要になります。

• HTTPクライアント: APIに対してリクエストを送信し、レスポンスを受信する機能。
• JSONシリアライズ/デシリアライズ: Rustのデータ構造（構造体など）とJSON形式の文字列を相互に変換する機能。

このステップでは、Rustで非常に人気のあるクレート（ライブラリ）である reqwest と serde を使って、JSON APIとの連携とデータのシリアライズ・デシリアライズを行う方法を学びます。

まず、Cargo.tomlに必要なクレートを追加します。reqwest はHTTP通信、serde はシリアライズ/デシリアライズのフレームワーク、serde_json はJSON形式の具体的な処理、tokio は非同期ランタイムです。

Cargo.toml の [dependencies] セクションに以下のように記述します。

[dependencies]
reqwest = { version = "0.12", features = ["json"] } # HTTPクライアント、json機能を有効化
serde = { version = "1.0", features = ["derive"] }   # シリアライズ/デシリアライズのフレームワーク、deriveマクロを有効化
serde_json = "1.0"                                # JSON形式の処理
tokio = { version = "1", features = ["full"] }      # 非同期ランタイム

reqwest の json フィーチャーを有効にすることで、レスポンスボディを直接JSONとしてパースしたり、リクエストボディにJSONデータを簡単に含めたりできるようになります。serde の derive フィーチャーは、構造体や列挙型に #[derive(Serialize, Deserialize)] を追加するだけで、簡単にシリアライズ・デシリアライズを実装できるようにします。

serde はRustのデータ構造と様々なデータ形式（JSON, YAML, TOMLなど）を相互に変換するためのフレームワークです。JSONを扱うには serde_json クレートを併用します。

基本的な使い方は、変換したいRustの構造体や列挙型に serde::Serialize と serde::Deserialize トレイトを実装することです。多くの場合、deriveマクロを使うのが最も簡単です。

データ構造の定義

例として、ユーザー情報を表す構造体を定義してみましょう。

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)] // Debugも追加しておくと表示に便利
struct User {
    id: u64,
    username: String,
    email: String,
    active: bool,
}

#[derive(Serialize, Deserialize)] を追加するだけで、この User 構造体はJSONとの間で相互に変換可能になります。

シリアライズ (Rust → JSON)

Rustのデータ構造のインスタンスをJSON文字列に変換するには、serde_json::to_string や serde_json::to_string_pretty（整形されたJSON）を使います。

use serde_json;

fn main() {
    let user = User {
        id: 1,
        username: "rustacean".to_string(),
        email: "user@example.com".to_string(),
        active: true,
    };

    // JSON文字列にシリアライズ
    let json_string = serde_json::to_string(&user).expect("シリアライズに失敗しました");
    println!("Serialized JSON: {}", json_string);

    // 整形されたJSON文字列にシリアライズ
    let pretty_json_string = serde_json::to_string_pretty(&user).expect("シリアライズに失敗しました");
    println!("\nPretty Serialized JSON:\n{}", pretty_json_string);
}

// --- User構造体の定義は省略 ---
#[derive(Serialize, Deserialize, Debug)]
struct User {
    id: u64,
    username: String,
    email: String,
    active: bool,
}
// --- ここまで ---

実行すると、user インスタンスがJSON文字列に変換されて出力されます。

デシリアライズ (JSON → Rust)

JSON文字列をRustのデータ構造のインスタンスに変換するには、serde_json::from_str を使います。

use serde_json;

fn main() {
    let json_data = r#"
        {
            "id": 2,
            "username": "ferris",
            "email": "ferris@rust-lang.org",
            "active": true
        }
    "#;

    // JSON文字列からUser構造体にデシリアライズ
    let user: User = serde_json::from_str(json_data).expect("デシリアライズに失敗しました");

    println!("\nDeserialized User: {:?}", user);
    println!("Username: {}", user.username);
}

// --- User構造体の定義は省略 ---
#[derive(Serialize, Deserialize, Debug)]
struct User {
    id: u64,
    username: String,
    email: String,
    active: bool,
}
// --- ここまで ---

json_data 文字列が User 構造体のインスタンスに変換され、その内容が表示されます。

reqwest クレートを使うと、HTTPリクエストを簡単に送信できます。ここでは、公開されているJSON API (例: JSONPlaceholder) を使って、データの取得 (GET) と送信 (POST) を試してみましょう。

GETリクエスト: APIからデータを取得してデシリアライズ

APIからJSONデータを取得し、それをRustの構造体にデシリアライズする例です。

use reqwest;
use serde::Deserialize;
use tokio; // tokioランタイムを使用

#[derive(Deserialize, Debug)]
struct Post {
    #[serde(rename = "userId")] // JSONのキー名とRustのフィールド名が異なる場合
    user_id: u64,
    id: u64,
    title: String,
    body: String,
}

#[tokio::main] // main関数を非同期関数にする
async fn main() -> Result<(), reqwest::Error> {
    let api_url = "https://jsonplaceholder.typicode.com/posts/1";

    println!("{} からデータを取得中...", api_url);

    // GETリクエストを送信し、レスポンスを取得
    let response = reqwest::get(api_url).await?;

    // レスポンスボディをJSONとしてデシリアライズ
    // reqwestのjson()メソッドは内部でserde_jsonを呼び出す
    if response.status().is_success() {
        let post: Post = response.json().await?;
        println!("取得した投稿データ: {:?}", post);
        println!("タイトル: {}", post.title);
    } else {
        println!("エラーが発生しました: {}", response.status());
    }

    Ok(())
}

このコードは、指定されたURLにGETリクエストを送り、返ってきたJSONデータを Post 構造体にデシリアライズして表示します。

• #[tokio::main] マクロを使って main 関数を非同期関数のエントリーポイントにします。
• reqwest::get(url).await? でGETリクエストを非同期に実行し、Result を処理します (?演算子)。
• response.json::().await? でレスポンスボディを直接 Post 型にデシリアライズします。reqwest の json フィーチャーが必要です。
• #[serde(rename = "userId")] のようにアトリビュートを使うことで、JSONのキー名（キャメルケース）とRustのフィールド名（スネークケース）の違いを吸収できます。

POSTリクエスト: RustデータをシリアライズしてAPIに送信

RustのデータをJSONにシリアライズし、それをAPIにPOSTリクエストで送信する例です。

use reqwest;
use serde::{Serialize, Deserialize};
use tokio;

#[derive(Serialize, Deserialize, Debug)]
struct NewPost {
    #[serde(rename = "userId")]
    user_id: u64,
    title: String,
    body: String,
}

#[derive(Deserialize, Debug)] // レスポンスを受け取るための構造体
struct CreatedPost {
    id: u64,
    #[serde(rename = "userId")]
    user_id: u64,
    title: String,
    body: String,
}


#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let api_url = "https://jsonplaceholder.typicode.com/posts";

    let new_post = NewPost {
        user_id: 1,
        title: "Rustからの新しい投稿".to_string(),
        body: "reqwest と serde を使ってPOSTリクエストを送信しています。".to_string(),
    };

    println!("{} にデータを送信中...", api_url);

    let client = reqwest::Client::new();
    let response = client.post(api_url)
        .json(&new_post) // 送信するデータをjson()メソッドで指定 (内部でシリアライズされる)
        .send()
        .await?;

    if response.status().is_success() {
        // APIによっては作成されたリソースが返ってくる
        let created_post: CreatedPost = response.json().await?;
        println!("作成された投稿データ: {:?}", created_post);
        println!("新しい投稿ID: {}", created_post.id);
    } else {
        println!("エラーが発生しました: {} {}", response.status(), response.text().await?);
    }

    Ok(())
}

このコードは、NewPost 構造体のインスタンスを作成し、それをJSONにシリアライズして指定されたURLにPOSTリクエストとして送信します。

• reqwest::Client::new() でHTTPクライアントを作成します。ヘッダーの設定など、より細かい制御が可能です。
• client.post(url).json(&data).send().await? でPOSTリクエストを作成し、.json(&data) でリクエストボディに含めるデータを指定します。このデータは自動的にJSONにシリアライズされます。
• APIからのレスポンス（通常、作成されたリソースの情報が含まれる）を CreatedPost 構造体にデシリアライズして表示しています。

API連携では様々なエラーが発生する可能性があります。

実際のアプリケーションでは、これらのエラーを網羅的に考慮し、ユーザーに分かりやすいフィードバックを返したり、ログに記録したりする堅牢なエラーハンドリング機構を実装することが重要です。

Rustの Result 型と ? 演算子、そして thiserror や anyhow といったエラーハンドリング支援クレートを活用すると、エラー処理をより簡潔かつ効果的に記述できます。

このステップでは、RustでJSON APIと連携するための基本的な方法を学びました。

• serde と serde_json を使って、Rustのデータ構造とJSON文字列を相互に変換（シリアライズ・デシリアライズ）する方法。
• reqwest を使って、HTTPのGETリクエストやPOSTリクエストを送信し、APIと通信する方法。
• async/await と tokio を使った非同期処理の基本。
• API連携における基本的なエラーハンドリングの考え方。

これらの知識は、Webサービス、CLIツール、デスクトップアプリケーションなど、ネットワーク通信を行う多くのRustアプリケーション開発において不可欠です。ぜひ実際に手を動かして、様々なAPIとの連携を試してみてください！🚀