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

生徒

「先生、SymfonyでAPIを作りたいんですけど、普通のコントローラとは何が違うんですか？」

先生

「いい質問ですね。APIコントローラは、画面を表示するのではなく、データだけをやり取りするための特別なコントローラなんですよ。」

生徒

「データだけってどういうことですか？」

先生

「たとえば、天気アプリが気温のデータだけを取得するときのように、見た目ではなく“中身の情報”をやり取りするんです。そういった処理を正しく設計するためのポイントを、これから解説していきますね。」

1. APIコントローラとは？

API（エーピーアイ）は「アプリ同士がデータをやり取りする仕組み」のことです。たとえば、スマホアプリが天気の情報を取得したり、別のサービスと連携したりする時に使われます。

Symfonyでは、HTML画面ではなくJSON形式でデータを返すコントローラのことを「APIコントローラ」と呼びます。

2. SymfonyでAPIレスポンスを返す基本の書き方

APIでは、JsonResponseという特別なレスポンス形式を使ってデータを返します。


use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;

#[Route('/api/hello', name: 'api_hello')]
public function hello(): JsonResponse
{
    return new JsonResponse([
        'message' => 'こんにちは、APIの世界へようこそ！'
    ]);
}

このように書くだけで、画面ではなく「JSON形式」でデータが返されます。

3. 実際の出力例


{
    "message": "こんにちは、APIの世界へようこそ！"
}

このような「鍵と値のセット」でデータをやり取りするのがJSON形式の特徴です。

4. APIコントローラの設計で気をつけるポイント

SymfonyでAPIを設計するときには、いくつかのベストプラクティス（おすすめの書き方）があります。

必ずJsonResponseを使う（HTMLではなくデータを返す）
エラーハンドリング（データが無い場合は404など）をきちんと行う
HTTPメソッド（GET, POSTなど）を正しく使い分ける
ルーティングは「/api/〜」のように分かりやすくする
使わない情報は返さない（セキュリティ面でも重要）

5. Symfonyで404エラーを返すAPIコントローラの例

データが存在しない場合は、適切に404エラーを返すことが大切です。


use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

#[Route('/api/item/{id}', name: 'api_item')]
public function getItem(int $id): JsonResponse
{
    $item = null; // 本来はデータベースから取得する

    if (!$item) {
        throw new NotFoundHttpException('データが見つかりません');
    }

    return new JsonResponse([
        'id' => $id,
        'name' => 'テスト商品'
    ]);
}

このように、SymfonyではAPIでもエラー制御が可能です。

6. APIコントローラでGET・POSTを使い分けよう

GETメソッドは「情報を取得する」、POSTメソッドは「新しいデータを送る」ために使います。

Symfonyでは、ルートにmethods: ['POST']のように書くことで、POST専用にすることができます。


#[Route('/api/create', name: 'api_create', methods: ['POST'])]
public function create(): JsonResponse
{
    return new JsonResponse([
        'result' => 'データを登録しました'
    ]);
}