Next.jsで学ぶReact講座 90日コース | Next.js基礎 - Day 46:Route Handlers

React Next.jsで学ぶReact講座90日コース
スポンサーリンク
スポンサーリンク

Day 46:Route Handlersで自分のAPIを作る

Day 46では、Next.js App RouterのRoute Handlersを学びます。今日は、GET、POST、Request、Responseの基本を理解しながら、実際に自分でAPIを作るところまで進めます。Next.jsのRoute Handlersは、appディレクトリ内の route.ts または route.js で定義する仕組みで、Web標準のRequest/Response APIを使って独自のAPIエンドポイントを作れます。Route Handlersで使えるHTTPメソッドには GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS があり、未対応メソッドには 405 Method Not Allowed が返されます。 (🔗 nextjs.org)

初心者向けに一言でいうと、Route Handlersは「Next.jsの中にAPIサーバーの入口を作る仕組み」です。これによって、ページを表示するだけでなく、データを返したり、投稿を受け取ったりできるようになります。なお、Route Handlersはappディレクトリ専用で、Pages Router時代のAPI Routesに相当する仕組みです。 (🔗 nextjs.org)

Day 46で学ぶこと

  • Route Handlersとは何かを理解します。
  • `GET`と`POST`の違いを理解します。
  • `Request`からデータを受け取る方法を学びます。
  • `Response`や`NextResponse`で結果を返す方法を学びます。
  • 実際に`/api/posts`という自作APIを作ります。
  • APIをテストする方法も学びます。

Route Handlersとは

Route Handlersとは、特定のURLに対して自分でリクエスト処理を書く仕組みです。Next.js公式では、Route Handlersはappディレクトリ内の route.js|ts で定義し、WebのRequest/Response APIを使ってカスタムリクエストハンドラーを作るものと説明されています。 (🔗 nextjs.org)

たとえば、app/api/posts/route.ts を作ると、/api/posts というURLに対して処理を書けます。ここに GET 関数を書けば一覧取得APIになり、POST 関数を書けば新規作成APIになります。Route Handlersはpage.tsxやlayout.tsxのようにファイル構成でルーティングされますが、同じセグメント階層に page.tsx と route.ts は共存できません。 (🔗 nextjs.org)

GETとPOSTの違い

APIを学ぶとき、まずGETとPOSTを区別できることが大切です。

  • GET:データを取得するときに使います。
  • POST:新しいデータを送信・作成するときに使います。

Next.jsのRoute Handlersでは、export async function GET() や export async function POST() のように、HTTPメソッド名そのものを関数名にして処理を書きます。対応メソッドだけを書けばよく、未実装のHTTPメソッドに対してはNext.jsが 405 Method Not Allowed を返します。 (🔗 nextjs.org)

Requestとは何か

Requestは、「相手が何を送ってきたか」が入っているオブジェクトです。URL、ヘッダー、本文、クエリ文字列などを読み取れます。Route Handlersの各メソッドは、基本的にWeb標準のRequestオブジェクトを受け取ります。Next.jsには NextRequest という拡張版もあり、nextUrl などの便利な機能を使えます。 (🔗 nextjs.org)

たとえばPOST送信では、await request.json() でJSON本文を取り出します。GETリクエストのクエリ文字列を読みたいときは、new URL(request.url) や request.nextUrl のような方法が使えます。 (🔗 nextjs.org)

Responseとは何か

Responseは、「こちらが相手に何を返すか」を表すオブジェクトです。JSONデータ、ステータスコード、ヘッダーなどをまとめて返します。Next.jsでは標準のResponseも使えますし、より書きやすい NextResponse も使えます。NextResponse はWeb標準のResponseを拡張したヘルパーで、NextResponse.json() のような便利メソッドがあります。 (🔗 nextjs.org)

初心者には、まず NextResponse.json() を使う形がおすすめです。理由は、JSONを返すコードが短くなり、ステータスコードも一緒に書きやすいからです。 (🔗 nextjs.org)

今日作るAPIの完成イメージ

今日は、簡単なブログ投稿APIを作ります。URLは次の1つです。

  • `GET /api/posts`:投稿一覧を返します。
  • `POST /api/posts`:新しい投稿を受け取って追加します。

ファイル構成は次のようにします。

src/
├── app/
│   ├── api/
│   │   └── posts/
│   │       └── route.ts
│   ├── api-test/
│   │   └── page.tsx
│   └── layout.tsx

Route Handlersは app ディレクトリの中で自由にネストできるので、app/api/posts/route.ts は自然に /api/posts に対応します。 (🔗 nextjs.org)

Step 1:最小のGET APIを作る

まずは、データを返すだけの最小APIから始めます。

src/app/api/posts/route.ts

// NextResponseを読み込みます
import { NextResponse } from "next/server";

// 投稿一覧を返すGET APIです
export async function GET() {
  // 学習用の固定データです
  const posts = [
    { id: 1, title: "Next.js入門" },
    { id: 2, title: "App Router基礎" },
    { id: 3, title: "Route Handlers入門" },
  ];

  // JSON形式で返します
  return NextResponse.json(posts);
}
TypeScript

このコードで、/api/posts にアクセスするとJSON配列が返ります。Route Handlersでは GET 関数をexportすることでGETリクエストに応答し、NextResponse.json() でJSONレスポンスを返せます。 (🔗 nextjs.org)

Step 2:ブラウザーでAPIを確認する

開発サーバーを起動した状態で、ブラウザーで次を開きます。

http://localhost:3000/api/posts

すると、JSONがそのまま表示されるはずです。これは「ページ」ではなく「APIの返り値」です。見た目は地味ですが、すでに自分のAPIが動いています。

Step 3:Requestを受け取る形に変える

次に、GET関数でRequestを受け取る形にしてみます。今は本文を使わなくても、Requestがどう入ってくるか知っておくことが大切です。

// NextResponseを読み込みます
import { NextResponse } from "next/server";

// GETリクエストを処理します
export async function GET(request: Request) {
  // リクエストURLを確認できます
  console.log(request.url);

  const posts = [
    { id: 1, title: "Next.js入門" },
    { id: 2, title: "App Router基礎" },
    { id: 3, title: "Route Handlers入門" },
  ];

  return NextResponse.json(posts);
}
TypeScript

このように、Route HandlersのメソッドにはRequestを受け取れます。必要なければ省略できますが、URLやヘッダー、本文を扱うなら受け取る形にします。 (🔗 nextjs.org)

Step 4:クエリ文字列を読む

GET APIでは、?limit=2 のようなクエリ文字列を使うことがあります。その場合はURLを解析します。

// NextResponseを読み込みます
import { NextResponse } from "next/server";

// GETリクエストを処理します
export async function GET(request: Request) {
  // URLオブジェクトを作ります
  const { searchParams } = new URL(request.url);

  // クエリ文字列からlimitを取得します
  const limit = searchParams.get("limit");

  const posts = [
    { id: 1, title: "Next.js入門" },
    { id: 2, title: "App Router基礎" },
    { id: 3, title: "Route Handlers入門" },
  ];

  // limitがあるときだけ件数を絞ります
  const result = limit ? posts.slice(0, Number(limit)) : posts;

  // JSONで返します
  return NextResponse.json(result);
}
TypeScript

こうすると、/api/posts?limit=2 のようなURLで件数を変えられます。Next.jsではRequestのURLからクエリ文字列を読めますし、NextRequestを使うとnextUrlでも扱えます。 (🔗 nextjs.org)

Step 5:POST APIを追加する

ここからがAPIらしい部分です。新しい投稿を受け取るPOSTを追加します。

src/app/api/posts/route.ts

// NextResponseを読み込みます
import { NextResponse } from "next/server";

// 学習用の投稿データです
const posts = [
  { id: 1, title: "Next.js入門" },
  { id: 2, title: "App Router基礎" },
];

// 投稿一覧を返すGET APIです
export async function GET() {
  // 現在の投稿一覧を返します
  return NextResponse.json(posts);
}

// 新しい投稿を受け取るPOST APIです
export async function POST(request: Request) {
  // リクエスト本文のJSONを読み取ります
  const body = await request.json();

  // 送られてきたtitleを取り出します
  const title = body.title;

  // titleが空ならエラーを返します
  if (!title || typeof title !== "string") {
    return NextResponse.json(
      { message: "titleは必須です。" },
      { status: 400 }
    );
  }

  // 新しい投稿データを作ります
  const newPost = {
    id: posts.length + 1,
    title,
  };

  // 配列に追加します
  posts.push(newPost);

  // 作成成功として201で返します
  return NextResponse.json(newPost, { status: 201 });
}
TypeScript

POSTでは、await request.json() で本文を読み取り、入力値を確認してから返します。JSONレスポンスにステータスコードを付けるなら NextResponse.json(data, { status: 201 }) の形が便利です。 (🔗 nextjs.org)

Step 6:POSTで何をしているかを分解して理解する

このPOST処理は、初心者にとって重要な流れが詰まっています。

  • まず`request.json()`で送信されたデータを読み取ります。
  • 次に、必要な値がちゃんと入っているか確認します。
  • 問題があれば400番台のエラーを返します。
  • 問題がなければ新しいデータを作ります。
  • 最後に201で成功レスポンスを返します。

APIでは「受け取って終わり」ではなく、入力確認と適切なステータスコードが非常に重要です。これはNext.jsに限らず、Web API全体の基本です。

Step 7:テスト用ページを作る

APIだけ作っても、初心者は使い方を実感しにくいことがあります。そこで、ブラウザーから試せる簡単なページも作ります。

src/app/api-test/page.tsx

// このページはブラウザーで操作するのでClient Componentにします
"use client";

// useStateを読み込みます
import { useState } from "react";

// APIテストページです
export default function ApiTestPage() {
  // 投稿一覧を管理します
  const [posts, setPosts] = useState<{ id: number; title: string }[]>([]);

  // 入力欄の値を管理します
  const [title, setTitle] = useState("");

  // GET APIを呼び出して一覧を取得します
  async function fetchPosts() {
    // 自作APIへGETリクエストを送ります
    const response = await fetch("/api/posts");

    // JSONに変換します
    const data = await response.json();

    // 画面に反映します
    setPosts(data);
  }

  // POST APIを呼び出して新規作成します
  async function createPost() {
    // 自作APIへPOSTリクエストを送ります
    const response = await fetch("/api/posts", {
      method: "POST",
      headers: {
        // 送信データがJSONであることを伝えます
        "Content-Type": "application/json",
      },
      // titleをJSON文字列に変換して送ります
      body: JSON.stringify({ title }),
    });

    // レスポンスが失敗なら処理を止めます
    if (!response.ok) {
      alert("投稿の作成に失敗しました。");
      return;
    }

    // 作成後に入力欄を空にします
    setTitle("");

    // 一覧を再取得します
    fetchPosts();
  }

  return (
    <main>
      <h1>APIテスト</h1>

      <button type="button" onClick={fetchPosts}>
        投稿一覧を取得する
      </button>

      <div>
        <input
          type="text"
          value={title}
          placeholder="新しい投稿タイトル"
          // 入力値をstateへ保存します
          onChange={(event) => setTitle(event.target.value)}
        />
        <button type="button" onClick={createPost}>
          投稿を追加する
        </button>
      </div>

      <ul>
        {posts.map((post) => (
          // 投稿一覧を表示します
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </main>
  );
}
TSX

これで、/api-test から自分のAPIを実際に呼び出せます。学習初期は、このように「APIを作る側」と「APIを使う側」を両方触ると理解が一気に深まります。

Step 8:ResponseとNextResponseの違い

Route Handlersでは、標準のResponseを返しても動きます。たとえば次のようにも書けます。

// 標準のResponseを使う例です
export async function GET() {
  // JSON文字列を返します
  return new Response(JSON.stringify({ message: "Hello API" }), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
    },
  });
}
TypeScript

ただし、Next.jsでは NextResponse.json() のような便利メソッドがあり、JSONレスポンスやCookie操作などを簡潔に書けます。NextResponseはWeb標準Responseの拡張です。 (🔗 nextjs.org)

Step 9:GETのキャッシュにも触れておく

Route HandlersのGETは、内容によってキャッシュを考える場面があります。Next.jsでは、GETレスポンスをキャッシュしたいときにルート設定を使えます。たとえば export const dynamic = 'force-static' のような設定があります。 (🔗 nextjs.org)

ただし、Day 46の段階では、まずは次のように考えれば十分です。

  • 学習中の自作APIは、まず正しく動くことを優先します。
  • キャッシュ最適化は、APIの意味が分かってから追加します。

Step 10:Route Handlersを使うべき場面

ここは実務でも重要です。Route Handlersは便利ですが、何でもかんでも自分のAPIにすればよいわけではありません。

  • ブラウザーから送信されるフォーム処理を受けたいとき。
  • 外部サービスのWebhook受信口を作りたいとき。
  • クライアント側から安全に呼べる自分用のAPIが必要なとき。
  • モバイルアプリや別フロントエンドから使うAPIを用意したいとき。

一方で、Server Componentの中で使うだけのデータ取得なら、外部データソースへ直接アクセスするほうが自然な場面もあります。Next.js公式のBackend for Frontendガイドでも、Server Componentsでは不要な内部HTTP往復を避けるため、データソースへ直接アクセスすることが勧められています。 (🔗 nextjs.org)

Step 11:セキュリティ上の注意

APIを作るときは、見た目以上にセキュリティが大切です。特に初心者が意識すべき点は次の通りです。

  • 受け取った値を信用しない:POST本文は必ず検証します。
  • 詳細な内部エラーをそのまま返しすぎない:利用者向けには簡潔なメッセージにします。
  • 認証前提の情報を誰でも取得できるAPIにしない:公開範囲を意識します。
  • ヘッダーを無差別に転送しない:認証情報やCookieの漏えいにつながる可能性があります。Next.js公式も、ヘッダー転送は安全なものだけを選んで行うよう注意しています。

今回の例は学習用なのでメモリ上の配列を使っていますが、実務ではデータベース保存、認証、バリデーション、レート制限なども必要になります。

Step 12:よくあるつまずき

  • `route.ts`ではなく`page.tsx`を作ってしまう:APIは `route.ts` です。
  • 同じ階層に`page.tsx`と`route.ts`を置こうとする:同一セグメントでは共存できません。
  • POSTで`request.json()`を忘れる:本文を読まないと送信データを扱えません。
  • 入力チェックをせずに保存する:空文字や不正データが混ざります。
  • GETとPOSTの役割を混ぜる:取得はGET、作成はPOSTと分けて考えると整理しやすいです。

Step 13:初心者向けテンプレート

最後に、最小テンプレートを載せておきます。

GETテンプレート

// JSONレスポンス用のヘルパーを読み込みます
import { NextResponse } from "next/server";

// GETリクエストを処理します
export async function GET() {
  // 固定データを返します
  return NextResponse.json([
    { id: 1, name: "Item 1" },
    { id: 2, name: "Item 2" },
  ]);
}
TypeScript

POSTテンプレート

// JSONレスポンス用のヘルパーを読み込みます
import { NextResponse } from "next/server";

// POSTリクエストを処理します
export async function POST(request: Request) {
  // 送信されたJSON本文を読み取ります
  const body = await request.json();

  // 必須項目を確認します
  if (!body.name) {
    return NextResponse.json(
      { message: "nameは必須です。" },
      { status: 400 }
    );
  }

  // 成功レスポンスを返します
  return NextResponse.json(
    { id: 1, name: body.name },
    { status: 201 }
  );
}
TypeScript

クエリ文字列テンプレート

// JSONレスポンス用のヘルパーを読み込みます
import { NextResponse } from "next/server";

// GETリクエストを処理します
export async function GET(request: Request) {
  // URLからクエリ文字列を取得します
  const { searchParams } = new URL(request.url);

  // qパラメータを読み取ります
  const q = searchParams.get("q");

  // 結果を返します
  return NextResponse.json({ keyword: q });
}
TypeScript

Day 46のチェックリスト

  • Route Handlersが `app` ディレクトリ内の `route.ts` で作る仕組みだと説明できます。
  • `GET`でデータ取得、`POST`でデータ作成の基本を説明できます。
  • `Request`からURLやJSON本文を読み取れます。
  • `NextResponse.json()`でJSONレスポンスを返せます。
  • `/api/posts` のような自分のAPIを作れます。
  • 入力値の基本的な検証が必要だと理解しています。
  • 同じセグメントに`page.tsx`と`route.ts`を置けないことを理解しています。

まとめ

Day 46では、Next.js App RouterのRoute Handlersを使って、自分のAPIを作る方法を学びました。Route Handlersは app ディレクトリ内の route.ts に書き、GET や POST の関数をexportすることで、Web標準のRequest/Response APIを使ったエンドポイントを作れます。JSONを返すときは NextResponse.json() が便利です。 (🔗 nextjs.org)

実践では、GET /api/posts で投稿一覧を返し、POST /api/posts で新しい投稿を受け取るAPIを作りました。ここまで理解できれば、次は PUT や DELETE を追加して更新・削除APIへ発展させたり、動的ルートを使って /api/posts/1 のような詳細APIを作ったりできます。Route Handlersは、Next.jsで「ページを作る」から「アプリ全体を作る」へ進むための重要な一歩です。

タイトルとURLをコピーしました