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

生徒

「Play FrameworkでAPIを作りたいのですが、JSONレスポンスを返す方法がよく分かりません…。どうすればよいですか？」

先生

「Play Frameworkでは、組み込みのJSONサポートを使えば、簡単にJSON形式のレスポンスを返すことができますよ。ウェブアプリケーションやREST APIを作るときにとても便利です。」

生徒

「コントローラからJSONを返す具体的な書き方を知りたいです！」

先生

「では、Play FrameworkでJSONレスポンスを返す基本を丁寧に説明していきましょう。」

1. Play FrameworkでJSONを返す理由

現代のウェブ開発では、スマートフォンアプリやシングルページアプリケーション、外部連携システムなどが増えてきたため、サーバー側でJSON形式のレスポンスを返すことが非常に重要になっています。Play Frameworkは、JavaとScalaで構築される高速なウェブフレームワークで、REST APIの開発と相性がよく、標準ライブラリでJSONの操作が簡単に行えるようになっています。初心者がPlay Frameworkを使ってAPI開発を学ぶ際にも、JSONレスポンスの仕組みを理解しておくことは欠かせません。

特にウェブアプリケーションとフロントエンドが分離された構成では、データのやり取りをJSONに統一することで処理がシンプルになります。そのため、Play Frameworkが提供するJsonユーティリティは非常に役立ちます。この記事では、Play Frameworkのリクエスト処理とレスポンス生成を理解しつつ、自然な流れでJSONレスポンスを返す方法を解説していきます。

2. Play FrameworkでJSONレスポンスを返す基本

Play Frameworkでは、コントローラのメソッド内でok()メソッドとJson.toJson()を組み合わせることで、簡単にJSON形式を返すことができます。JavaのオブジェクトをそのままJSONに変換できるため、外部とのデータ交換がとても効率的に行えます。

ここでは、簡単な文字列やリスト、オブジェクトを返す例を順番に紹介します。まずは最もシンプルな例から確認していきましょう。


package controllers;

import play.mvc.*;
import play.libs.Json;

public class JsonController extends Controller {

    public Result simpleJson() {
        return ok(Json.toJson("こんにちは、Play Framework！"));
    }
}

3. JSONオブジェクトを返す例

実際のAPI開発では、文字列だけではなく複数の値をまとめたオブジェクトを返すことが多くなります。Play Frameworkでは、JavaのMapや独自クラスを使ってデータ構造を作成し、Json.toJson()で変換することができます。


package controllers;

import play.mvc.*;
import play.libs.Json;
import java.util.*;

public class JsonController extends Controller {

    public Result objectJson() {
        Map<String, Object> data = new HashMap<>();
        data.put("message", "ユーザー情報");
        data.put("id", 123);
        data.put("status", "success");
        return ok(Json.toJson(data));
    }
}

4. 独自クラスをJSONへ変換して返す方法

より現実的なAPIでは、ユーザー情報や商品情報など、複雑なデータ構造を持つクラスをJSONとして返す必要があります。Play Frameworkでは、Javaクラスにフィールドを定義してpublicとして公開するだけでJSON変換が可能です。特別な設定をしなくても、Playが自動的にフィールドを読み取ってJSONに変換してくれます。


package models;

public class User {
    public String name;
    public int age;
    public String email;

    public User(String name, int age, String email) {
        this.name = name;
        this.age = age;
        this.email = email;
    }
}


package controllers;

import play.mvc.*;
import play.libs.Json;
import models.User;

public class JsonController extends Controller {

    public Result userJson() {
        User user = new User("山田太郎", 25, "taro@example.com");
        return ok(Json.toJson(user));
    }
}

5. JSONレスポンスとHTTPステータスコード

API開発では、レスポンスの内容だけでなく、適切なHTTPステータスコードを返すことも重要になります。Play Frameworkのok()やbadRequest()などを活用すると、状況に応じたステータスコードを簡単に設定できます。


public Result errorJson() {
    Map<String, String> error = new HashMap<>();
    error.put("error", "不正なリクエストです");
    return badRequest(Json.toJson(error));
}

このように、JSONとステータスコードを組み合わせることで、フロントエンド側はエラーハンドリングを行いやすくなります。

6. Play Frameworkのリクエストとレスポンスとの関連

Play Frameworkでは、リクエストを受け取って処理し、レスポンスとしてJSONを返すという一連の流れが非常に自然に構築できるようになっています。特に非同期処理やルーティングとの組み合わせによって、柔軟なAPI設計が可能になります。リクエストパラメータを受け取り、その内容を元にJSONレスポンスを生成することも簡単です。


public Result greet(String name) {
    Map<String, String> data = new HashMap<>();
    data.put("message", "こんにちは、" + name + "さん！");
    return ok(Json.toJson(data));
}

このように、URLパラメータとJSONレスポンスの組み合わせを使えば、ユーザーごとに動的な結果を返すAPIを作ることができます。