このガイドでは、Next.jsでAPIを構築する方法について説明します。プロジェクトのセットアップ、App RouterとRoute Handlersの理解、複数のHTTPメソッドの処理、動的ルーティングの実装、再利用可能なミドルウェアロジックの作成、専用APIレイヤーを構築するタイミングの決定などをカバーします。
- 1. はじめに
- 2. Next.jsでAPIを構築する理由(とタイミング)
- 3. Route HandlersでAPIを作成
- 4. Web APIとの連携
- 5. 動的ルート
- 6. Next.jsをプロキシまたは転送層として使用
- 7. 共有「ミドルウェア」ロジックの構築
- 8. デプロイと「SPAモード」の考慮事項
- 9. APIエンドポイントを作成しない場合
- 10. すべてをまとめる
- 結論
- よくある質問
1. はじめに
1.1 Next.jsアプリの作成
新規プロジェクトを作成する場合は、次のコマンドを使用します:
注:
--api
フラグを指定すると、新しいプロジェクトのapp/
フォルダにサンプルのroute.ts
が自動的に含まれ、APIエンドポイントの作成方法が示されます。
1.2 App RouterとPages Router
- Pages Router: 従来、Next.jsはAPIに
pages/api/*
を使用していました。このアプローチはNode.jsのリクエスト/レスポンスオブジェクトとExpress風のAPIに依存していました。 - App Router (デフォルト): Next.js 13で導入されたApp Routerは、Web標準のRequest/Response APIを完全に採用しています。
pages/api/*
の代わりに、app/
ディレクトリ内の任意の場所にroute.ts
またはroute.js
ファイルを配置できます。
なぜ切り替えるのか? App Routerの「Route Handlers」はNode.js固有のAPIではなくWeb Platform Request/Response APIsに依存しているため、学習が簡素化され、異なるツール間で知識を再利用できます。
2. Next.jsでAPIを構築する理由(とタイミング)
-
複数クライアント向けの公開API
- Next.jsウェブアプリ、別のモバイルアプリ、またはサードパーティサービスが消費する公開APIを構築できます。例えば、ReactウェブサイトとReact Nativeモバイルアプリの両方から
/api/users
をフェッチする場合などです。
- Next.jsウェブアプリ、別のモバイルアプリ、またはサードパーティサービスが消費する公開APIを構築できます。例えば、ReactウェブサイトとReact Nativeモバイルアプリの両方から
-
既存バックエンドへのプロキシ
- 外部のマイクロサービスを単一のエンドポイントの背後に隠したり統合したりしたい場合があります。Next.js Route Handlersは、別の既存バックエンドへのプロキシまたは中間層として機能できます。例えば、リクエストをインターセプトし、認証を処理し、データを変換してから、アップストリームAPIにリクエストを渡すことができます。
-
Webhooksと統合
- Stripe、GitHub、Twilioなどからの外部コールバックやWebhookを受信する場合、Route Handlersで処理できます。
-
カスタム認証
- セッション、トークン、その他の認証ロジックが必要な場合、Next.js API層でクッキーを保存したり、ヘッダーを読み取ったり、適切なデータで応答したりできます。
注: 独自のNext.jsアプリのためのサーバーサイドデータフェッチのみが必要で(そのデータを外部と共有する必要がない場合)、Server Componentsがレンダリング中に直接データをフェッチするのに十分であれば、別のAPI層は必要ありません。
3. Route HandlersでAPIを作成
3.1 基本的なファイル設定
App Router (app/
) で、ルートを表すフォルダを作成し、その中に route.ts
ファイルを配置します。
例えば、/api/users
にエンドポイントを作成する場合:
3.2 1つのファイルで複数のHTTPメソッドを扱う
Pages RouterのAPIルート(単一のデフォルトエクスポートがあった)とは異なり、同じファイルから異なるHTTPメソッドを表す複数の関数をエクスポートできます。
これで、/api/users
にGETリクエストを送信するとユーザーリストが返され、同じURLにPOSTリクエストを送信すると新しいユーザーが追加されます。
4. Web APIとの連携
4.1 Request & Responseの直接使用
デフォルトでは、Route Handlerメソッド(GET
、POST
など)は標準のRequestオブジェクトを受け取り、標準のResponseオブジェクトを返す必要があります。
4.2 クエリパラメータ
4.3 ヘッダーとクッキー
cookies()
と headers()
関数は、Next.jsの他のサーバーサイドコードで共有ロジックを再利用する場合に便利です。Next.jsはまた、基本のWeb APIを拡張した NextRequest
と NextResponse
も提供します。
5. 動的ルート
動的パス(例: /api/users/:id
)を作成するには、フォルダ構造で動的セグメントを使用します:
このファイルは /api/users/123
のようなURLに対応し、123
がパラメータとしてキャプチャされます。
ここで、params.id
が動的セグメントを提供します。
6. Next.jsをプロキシまたは転送層として使用
一般的なシナリオは、既存のバックエンドサービスをプロキシすることです。リモートサーバーやバックエンドに送信する前に、リクエストを認証したり、ログを記録したり、データを変換したりできます:
これでクライアントは /api/external
を呼び出すだけでよく、Next.jsが残りを処理します。これは「Backend for Frontend(BFF)」とも呼ばれます。
7. 共有「ミドルウェア」ロジックの構築
複数のRoute Handlerに同じロジック(認証チェック、ロギングなど)を適用したい場合、ハンドラーをラップする再利用可能な関数を作成できます:
Route Handlerでは:
8. デプロイと「SPAモード」の考慮事項
8.1 標準的なNode.jsデプロイ
標準のNext.jsサーバーデプロイ(next startを使用)では、Route Handlers、Server Components、Middlewareなどの機能を使用でき、動的なリクエスト時情報を活用できます。
追加の設定は不要です。詳細はデプロイを参照してください。
8.2 SPA/静的エクスポート
Next.jsはまた、サイト全体を静的シングルページアプリケーション(SPA)として出力することをサポートしています。
次の設定で有効にできます:
静的エクスポートモードでは、Next.jsは純粋な静的HTML、CSS、JSを生成します。サーバーサイドコード(APIエンドポイントなど)は実行できません。APIが必要な場合は、別途ホストする(スタンドアロンのNode.jsサーバーなど)必要があります。
注:
- GET Route Handlers は、動的リクエストデータに依存しない場合静的エクスポート可能です。これらはoutフォルダ内の静的ファイルになります。
- 他のすべてのサーバー機能(動的リクエスト、クッキーの書き換えなど)は、純粋なSPAエクスポートではサポートされていません。
8.3 VercelでのAPIデプロイ
Next.jsアプリケーションをVercelにデプロイする場合、APIデプロイガイドを参照してください。これには、Vercel Firewallを通じたプログラムによるレート制限などのVercel機能も含まれます。Vercelはまた、APIアプローチで一般的に必要とされるCron Jobsも提供しています。
9. APIエンドポイント作成をスキップする場合
App RouterのReact Server Componentsを使用すると、公開エンドポイントを公開せずにサーバー上で直接データを取得できます:
データがNext.jsアプリ内でのみ使用される場合、公開APIはまったく必要ないかもしれません。
10. 全体のまとめ
- 新しいNext.jsプロジェクトを作成:
npx create-next-app@latest --api
- Route Handlersを追加:
app/
ディレクトリ内に作成(例:app/api/users/route.ts
) - HTTPメソッドをエクスポート: 同じファイル内で
GET
、POST
、PUT
、DELETE
などを定義 - Web標準APIを使用:
Request
オブジェクトを操作し、Response
を返す - 公開APIを構築: 他のクライアントがデータを利用する必要がある場合、またはバックエンドサービスをプロキシする場合
- 新しいAPIルートをフェッチ: クライアント側から(例: Client Component内または
fetch('/api/...')
で) - API作成を完全にスキップ: Server Componentで直接データを取得できる場合
- 共有「ミドルウェア」パターンを追加: 認証やその他の繰り返しロジック用(例:
withAuth()
) - デプロイ: サーバー機能が必要な場合はNode.js対応環境へ、静的SPAのみの場合は静的エクスポート
結論
Next.jsのApp RouterとRoute Handlersを使用すると、Webプラットフォームを直接活用した柔軟でモダンなAPI構築方法が得られます。これで次のことが可能です:
- 完全な公開APIを作成: Web、モバイル、サードパーティのクライアントで共有
- プロキシ: 既存の外部サービスへの呼び出しをカスタマイズ
- 再利用可能な「ミドルウェア」層を実装: 認証、ロギング、その他の繰り返しロジック用
- 動的ルーティング:
[id]
セグメントフォルダ構造を使用してリクエストをルーティング
よくある質問
Server Actionsについては?
Server Actionsは、クライアントから呼び出せる自動生成されたPOST
APIルートと考えることができます。
これらはデータの作成、更新、削除などの変更操作用に設計されています。Server Actionは、定義されたAPIルートへの明示的なfetch
を行うのではなく、通常のJavaScript関数のように呼び出します。
ネットワークリクエストは発生しますが、明示的に管理する必要はありません。URLパスは自動生成され、暗号化されているため、ブラウザで/api/users
のようなルートに手動でアクセスすることはできません。
Server Actionsを使用しつつ公開APIも提供する予定の場合は、コアロジックをData Access Layerに移動し、Server ActionとAPIルートの両方から同じロジックを呼び出すことを推奨します。
Route HandlersでTypeScriptは使えますか?
はい、Route HandlersでTypeScriptを使用できます。例えば、route
ファイルでRequest
とResponse
の型を定義できます。
Next.jsでのTypeScript使用について詳しく学べます。
認証のベストプラクティスは?
認証ドキュメントで詳しく説明しています。