- Day 46:Route Handlersで自分のAPIを作る
- Day 46で学ぶこと
- Route Handlersとは
- GETとPOSTの違い
- Requestとは何か
- Responseとは何か
- 今日作るAPIの完成イメージ
- Step 1:最小のGET APIを作る
- Step 2:ブラウザーでAPIを確認する
- Step 3:Requestを受け取る形に変える
- Step 4:クエリ文字列を読む
- Step 5:POST APIを追加する
- Step 6:POSTで何をしているかを分解して理解する
- Step 7:テスト用ページを作る
- Step 8:ResponseとNextResponseの違い
- Step 9:GETのキャッシュにも触れておく
- Step 10:Route Handlersを使うべき場面
- Step 11:セキュリティ上の注意
- Step 12:よくあるつまずき
- Step 13:初心者向けテンプレート
- Day 46のチェックリスト
- まとめ
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 });
}TypeScriptPOSTでは、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" },
]);
}TypeScriptPOSTテンプレート
// 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 });
}TypeScriptDay 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で「ページを作る」から「アプリ全体を作る」へ進むための重要な一歩です。
