🚀

【Next.js和訳】API Routes/Dynamic API Routes

2021.10.02に公開

Next.js

tech

この記事について

株式会社 UnReact はプロジェクトの一環としてNext.js ドキュメントの和訳を行っています。

この記事は、API Routes/Dynamic API Routesの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Dynamic API Routes

例

Basic API Routes

APIルートは、ダイナミックルートをサポートしており、pagesで使用されているのと同じファイル命名規則に従います。

たとえば、APIルートのpages/api/post/[pid].jsには、次のようなコードがあります。

export default function handler(req, res) {
  const { pid } = req.query
  res.end(`Post: ${pid}`)
}

これで、/api/post/abcへのリクエストは、Post: abcのようなテキストで応答します。

インデックスルートとダイナミックAPIルート

非常に一般的なRESTfulパターンは、次のようなルートを設定することです。

GET api/posts - ページ分割されたポストのリストを取得します。
GET api/posts/12345 - ポストID 12345を取得

これを2つの方法でモデル化します。

オプション１:
- /api/posts.js
- /api/posts/[postId].js
オプション２:
- /api/posts/index.js
- /api/posts/[postId].js

どちらも同等です。ダイナミックルート（キャッチオールルートを含む）はundefinedのstateを持たず、GET api/postsはどのような状況でも/api/posts/[postId].jsにマッチしないため、/api/posts/[postId].jsのみを使用するという第3の選択肢は有効ではありません。

すべてのAPIルートをキャッチ

括弧の中に3つのドット（...）を追加することで、すべてのパスを捕捉するようにAPIルートを拡張することができます。例えば、以下のようになります。

pages/api/post/[...slug].jsは、/api/post/aだけでなく、/api/post/a/b、/api/post/a/b/cなどにもマッチします。

Note

[...param]のように、slug以外の名前を使うことができます。

マッチしたパラメータは、クエリパラメータ（例ではslug）としてページに送信され、常に配列となります。したがって、パス/api/post/aには、次のようなqueryオブジェクトが含まれます。

{ "slug": ["a"] }

また、/api/post/a/bやその他のマッチするパスの場合は、以下のように、新しいパラメータが配列に追加されます。

{ "slug": ["a", "b"] }

pages/api/post/[...slug].jsのAPIルートは以下のようになります。

export default function handler(req, res) {
  const { slug } = req.query
  res.end(`Post: ${slug.join(', ')}`)
}

これで、/api/post/a/b/cへのリクエストは、Post: a, b, cのようなテキストで応答するようになります。

任意のキャッチオールAPIルート

キャッチオールルートは、パラメータを二重括弧（[[...slug]]）で囲むことでオプションにすることができます。

例えば、pages/api/post/[[...slug]].jsは、/api/post、/api/post/a、/api/post/a/bなどにマッチします。

キャッチオールルートとオプショナルキャッチオールルートの主な違いは、オプショナルの場合、パラメータのないルートもマッチすることです（上記の例では、/api/post）。

queryオブジェクトは以下の通りです。

{ } // GET `/api/post` (空のオブジェクト)
{ "slug": ["a"] } // `GET /api/post/a` (要素が一つの配列)
{ "slug": ["a", "b"] } // `GET /api/post/a/b` (要素が複数の配列)

注意点

定義済みのAPIルートは動的なAPIルートよりも優先され、動的なAPIルートはすべてのAPIルートをキャッチするよりも優先されます。以下の例を見てください。
- pages/api/post/create.js - /api/post/createにマッチします。
- pages/api/post/[pid].js - /api/post/1, /api/post/abcなどにはマッチしますが、/api/post/createにはマッチしません。
- pages/api/post/[...slug].js - /api/post/1/2や/api/post/a/b/cなどにはマッチしますが、/api/post/createや/api/post/abcにはマッチしません。