Route Handlersの使い方：GET・POSTとJSONの入力検証
app/api配下のroute.tsでHTTP APIを作成します。GETとPOST、JSON解析の失敗、入力検証、400・415・422の応答を実例で確認します。
app/api配下のroute.tsでHTTP APIを作成します。GETとPOST、JSON解析の失敗、入力検証、400・415・422の応答を実例で確認します。
対象環境と役割
App Routerで使う機能
この記事のApp Routerの例はNext.js 15以降の非同期リクエストAPIに合わせた書き方です。Next.js 16ではCache Componentsを有効にしない構成を前提とします。Pages Routerの記事とは配置先・実行場所が異なるため、プロジェクトのルーターとバージョンを先に確認してください。
TypeScriptの例は5.2以降と、利用するNext.jsが対応するNode.jsを前提にします。app/layout.tsx を備えたApp Routerプロジェクトで実行してください。
引数・戻り値・受け渡すデータ
HTTPメソッド名の関数をexportし、Requestを受け取ってResponseを返します。Pages Routerの req, res を受け取るdefault handlerとは書き方が異なります。
コード例を動かす
app/api/echo/route.ts を作成する
以下はこのファイルとして配置する例です。既存ファイルへ追記する場合は、同じ名前のexportやURLが重複しないように統合してください。
export async function GET() {
return Response.json({ service: 'echo', accepts: 'POST application/json' });
}
export async function POST(request: Request) {
const mediaType = request.headers.get('content-type')?.split(';')[0].trim().toLowerCase();
if (mediaType !== 'application/json') {
return Response.json({ error: 'JSONで送信してください' }, { status: 415 });
}
let body: unknown;
try { body = await request.json(); }
catch { return Response.json({ error: 'JSONの形式が不正です' }, { status: 400 }); }
if (typeof body !== 'object' || body === null || !('message' in body) ||
typeof body.message !== 'string' || body.message.trim().length < 1 || body.message.length > 200) {
return Response.json({ error: 'messageは1〜200文字です' }, { status: 422 });
}
return Response.json({ message: body.message.trim() }, { headers: { 'Cache-Control': 'no-store' } });
}実行結果と処理の順序
GETで /api/echo を開くとAPIの説明が返ります。POSTはmessageを検証して返すだけで、保存処理はありません。メッセージの送受信を通じてステータスと本文の役割を確認できます。
空文字、JSONでない本文、Content-Typeの誤りを分けて返しています。実務では受信サイズ制限、レート制限、認証・認可を追加します。Cookie認証で更新するAPIならCSRF対策も設計します。
curlでPOSTを送る
curl -i http://localhost:3000/api/echo -H 'Content-Type: application/json' --data '{"message":"こんにちは"}'成功時はHTTP 200とmessageが返ります。フレームワークの起動ポートが違う場合はURLを変更してください。
つまずきやすい点と使い分け
Response.jsonの型定義を確認
この例の Response.json をTypeScriptで使うには対応するTypeScript・DOM型が必要です。古い構成では NextResponse.json を使う方法があります。記事掲載サイトの依存版を、そのまま最新サンプルの実行環境とみなさないでください。
GETとPOSTのキャッシュを分ける
Next.js 15以降のGET Route Handlerは既定でキャッシュされませんが、設定やデータ取得のキャッシュは別に確認します。個別ユーザーの情報を共有キャッシュへ入れないようにします。
静的出力で使えるか
この例はリクエストごとのサーバー処理を必要とします。output: 'export' で生成した out を配信するだけのサーバーでは実行できません。Next.jsのサーバー実行環境か別のAPIを用意します。
確認課題と実務への応用
自分で値を変えて確認する
開発サーバーの /api/echo にPOSTを送り、正常なmessage、空文字、不正JSON、別Content-Typeでそれぞれステータスを確認します。エラー本文に内部スタックや秘密値が出ないことも確認してください。
開発サーバーだけでなく、本番用ビルドと公開先でも確認します。URLを直接開く場合と画面内のリンクから遷移する場合、値がない場合と不正な値の場合を分けて試すと、型だけでは防げない入力の問題が見つかります。
公式資料と関連する記事
Googleの優先するニュース提供元にSEの部屋を追加
Googleで、いつも読みたい情報源を選べます。登録可否はGoogleの画面で確認できます。
候補にSEの部屋が表示されない場合は、まだ追加できません。