🚀

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

2021/10/02に公開・約2,700字

Next.js

tech

この記事について

この記事は、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などにもマッチします。

マッチしたパラメータは、クエリパラメータ（例では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にはマッチしません。