【Next.js和訳】API Routes/Dynamic API Routes
この記事について
この記事は、API Routes/Dynamic API Routesの記事を和訳したものです。
記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。
Dynamic 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 つの方法でモデル化します。
- オプション1:
/api/posts.js
/api/posts/[postId].js
- オプション2:
/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
にはマッチしません。
-
関連
次にすべきことについては、以下のセクションをお勧めします。
Discussion