Next.js の pages/api フォルダとは

Next.js で json を返す機能を作ろうと思ったら、
以下のよくわからない挙動に遭遇しました。

正常パターン

以下のファイルを設置します。

pages/api/test.tsx

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

http://localhost:3000/api/test
にアクセスすると
以下のレスポンスが返ってきます。

{"name":"John Doe"}

エラーあり

同じ内容のファイルを pages 以下に配置します。

pages/test.tsx

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

http://localhost:3000/test
にアクセスすると
エラーが発生します。

Server Error
TypeError: res.status is not a function

同じファイルなんですが、位置が違うだけで挙動が変わるのおかしいですね。

調べたところ

pages/api は特殊なフォルダらしいです。

API routes provide built in middlewares which parse the incoming request (req). Those middlewares are:

API Middlewares
https://nextjs.org/docs/api-routes/api-middlewares

こういうフレームワークの作法に慣れるのは、最初は大変ですね。