API ルート

例

API ルートは Next.js でAPIを構築する方法を提供しています。

pages/apiフォルダ内にあるすべてのファイルは /api/* にマッピングされ、pageの代わりに API エンドポイントとして扱われます。API ルートを使用しても、クライアントサイドのバンドルサイズが大きくなることはありません。これらはサーバーサイドのみのバンドルです。

例えば、以下の API ルート pages/api/user.js は json レスポンスを 200 ステータスコードとともに返します:

export default function handler(req, res) => {
  res.status(200).json({ name: 'John Doe' })
};

API ルートを使用するためには、関数(リクエストハンドラ)をデフォルトとしてエクスポートする必要があり、この関数は以下の 2 つのパラメータを受け取ります:

API ルートで異なる HTTP メソッドを処理するには、次のようにリクエストハンドラの req.method を使うことができます:

export default function handler(req, res) => {
  if (req.method === 'POST') {
    // POSTリクエストを処理します
  } else {
    // その他のHTTPメソッドを処理します
  }
};

API エンドポイントを取得するには、このセクションの最初にある例のどれかをご覧ください。

API ルートはCORSヘッダーを指定しません。つまり、標準では同一オリジンのみとなります。CORS ミドルウェアでリクエストハンドラをラップすることで挙動をカスタマイズすることができます。

API ルートを使用しても、クライアントサイドのバンドルサイズが大きくなることはありません。これらはサーバーサイドのみのバンドルです。

使い道

新規プロジェクトの場合、API ルートによって API 全体を一から構築できます。既存の API がある場合、API ルートを経由して API コールを転送する必要はありません。API ルートの他の使い道としては以下のようなものがあります:

API ルートはCORSヘッダーを指定しません。つまり、標準では同一オリジンのみとなります。CORS ミドルウェアでリクエストハンドラをラップすることで挙動をカスタマイズできます。
API ルートは next export と併用できません。