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

生徒

「Play FrameworkでAPIを作るとき、routesファイルはどう設計すればいいんですか？」

先生

「APIルーティングは、URLと処理の対応表をどう作るかがとても大切です。」

生徒

「とりあえず動けばいいと思っていましたが、設計も重要なんですね。」

先生

「後から修正しやすく、分かりやすいルーティングにしておくことがポイントです。」

1. APIルーティングとは何か

Play FrameworkにおけるAPIルーティングとは、ブラウザやアプリから送られてくるリクエストと、それを処理するコントローラのメソッドを結びつける仕組みです。

ルーティングはroutesファイルに記述され、URL、HTTPメソッド、処理内容が一覧表のように並びます。初心者の方は、電話帳や案内板をイメージすると理解しやすくなります。

APIの場合は特に、データをやり取りすることが目的になるため、 URLの分かりやすさと一貫性が重要になります。

2. API向けルーティング設計の基本

APIルーティング設計でまず意識したいのは、「何を操作するAPIなのか」がURLから分かることです。人が見ても意味が想像できるURLにすることで、保守性が高まります。

Play FrameworkではHTTPメソッドを使い分けることで、同じURLでも役割を明確に分けることができます。これにより、読みやすく整理されたAPIになります。

3. RESTを意識したURL設計

APIルーティングの設計では、RESTという考え方がよく使われます。 RESTとは、URLを「操作」ではなく「対象」に合わせて設計する考え方です。

例えば、ユーザー情報を扱う場合はusersという単語をURLに含めます。動作はHTTPメソッドで表現します。


GET     /api/users          controllers.UserController.list()
POST    /api/users          controllers.UserController.create()
GET     /api/users/:id      controllers.UserController.show(id: Long)

このように書くことで、URLを見ただけでAPIの役割が分かりやすくなります。初心者の方でも後から見返したときに理解しやすくなります。

4. Play Frameworkのroutesファイルの役割

routesファイルは、Play Frameworkの中でも特に重要な設定ファイルです。ここに書かれた内容が、アプリ全体の入口になります。

APIルーティングでは、画面表示用とAPI用を分けて設計することもよくあります。 URLにapiを含めることで、用途がはっきりします。

5. コントローラとの対応を意識する

ルーティングを書くときは、必ずコントローラとの対応関係を意識しましょう。一つのコントローラに役割を詰め込みすぎると、管理が難しくなります。


package controllers;

import play.mvc.*;

public class UserController extends Controller {

    public Result list() {
        return ok("ユーザー一覧");
    }

    public Result show(Long id) {
        return ok("ユーザー詳細: " + id);
    }

    public Result create() {
        return created("ユーザー作成");
    }
}

ルーティングとメソッド名を揃えておくことで、初心者でも処理の流れを追いやすくなります。