Catch-all API routes in NextJS

Introduction

Catch-all API routes let you handle many URL paths with one file. This helps when you want to respond to different paths without making many files.

You want one API file to handle multiple related paths.

You need to build a flexible API that accepts different URL depths.

You want to create dynamic routes that catch all sub-paths.

You want to simplify your API folder structure by grouping routes.

You want to handle unknown or variable paths gracefully.

Syntax

NextJS

pages/api/[...slug].js

export default function handler(req, res) {
  const { slug } = req.query;
  res.status(200).json({ slug });
}

The file name uses square brackets with three dots: [...slug].

The slug is an array of all parts of the URL after /api/.

Examples

This example uses params as the catch-all name. It returns all URL parts as an array.

NextJS

pages/api/[...params].js

export default function handler(req, res) {
  const { params } = req.query;
  res.status(200).json({ params });
}

This catch-all route is inside a blog folder, catching all paths under /api/blog/.

NextJS

pages/api/blog/[...slug].js

export default function handler(req, res) {
  const { slug } = req.query;
  res.status(200).json({ slug });
}

Using all as the parameter name to catch all API paths.

NextJS

pages/api/[...all].js

export default function handler(req, res) {
  const { all } = req.query;
  res.status(200).json({ all });
}

Sample Program

This API route catches all paths under /api/[...slug]. It returns a JSON with a message and the array of URL parts.

NextJS

export default function handler(req, res) {
  const { slug } = req.query;
  res.status(200).json({ message: 'Catch-all route works!', slug });
}

Important Notes

If the URL is /api/posts/2024/06, the slug array will be ["posts", "2024", "06"].

You can also create optional catch-all routes using [[...slug]].js to allow empty paths.

Catch-all routes help keep your API organized and flexible.

Summary

Catch-all API routes use [...name].js to catch many URL parts.

The caught parts come as an array in req.query.

This makes handling dynamic and nested API paths easy.

Practice

1. What does a catch-all API route file named [...slug].js in Next.js do?

easy

A. It catches all URL paths that match and provides the parts as an array in req.query.slug.

B. It only catches the root API path and ignores nested paths.

C. It catches only one specific URL path exactly matching slug.

D. It disables all API routes in the folder.

Solution

1. Step 1: Understand catch-all route naming

   In Next.js, files named with [...name].js catch all nested paths under that route.

2. Step 2: Check how parameters are passed

   The parts of the URL matched are passed as an array in req.query.name, here slug.

3. Final Answer:

   It catches all URL paths that match and provides the parts as an array in req.query.slug. -> Option A

4. Quick Check:

   Catch-all route = array in req.query [OK]

Hint: Catch-all uses [...name].js and returns array in req.query[name] [OK]

Common Mistakes:

• Thinking it catches only one path instead of many
• Expecting a string instead of an array in req.query
• Confusing catch-all with optional catch-all routes

2. Which of the following is the correct filename for a catch-all API route in Next.js?

easy

A. [slug].js

B. [...slug].js

C. slug.js

D. [slug...].js

Solution

1. Step 1: Recall catch-all route syntax

   Catch-all routes use three dots inside square brackets before the name, like [...slug].js.

2. Step 2: Compare options

   Only [...slug].js matches the correct syntax for catch-all routes.

3. Final Answer:

   [...slug].js -> Option B

4. Quick Check:

   Catch-all filename = [...name].js [OK]

Hint: Catch-all filenames always have three dots inside brackets [OK]

Common Mistakes:

• Using single brackets without dots for catch-all
• Placing dots outside brackets
• Missing brackets entirely

3. Given a catch-all API route file pages/api/[...params].js with this handler:

export default function handler(req, res) {
  res.json(req.query.params);
}

What will be the JSON response for a request to /api/a/b/c?

medium

A. "a/b/c"

B. {"params": "a/b/c"}

C. ["a", "b", "c"]

D. null

Solution

1. Step 1: Understand catch-all parameter passing

   The catch-all [...params] captures all path parts as an array in req.query.params.

2. Step 2: Check the handler response

   The handler returns req.query.params as JSON, so the response is the array of parts.

3. Final Answer:

   ["a", "b", "c"] -> Option C

4. Quick Check:

   Catch-all returns array of path parts [OK]

Hint: Catch-all returns array of URL parts in req.query [OK]

Common Mistakes:

• Expecting a string instead of an array
• Confusing JSON structure returned
• Not recognizing catch-all returns array

4. You wrote a catch-all API route pages/api/[...slug].js but when you request /api (no extra path), you get an error. What is the likely cause?

medium

A. You forgot to export the handler function.

B. The file name is incorrect; it should be [slug].js.

C. API routes cannot have dynamic segments.

D. Catch-all routes require at least one path segment; use optional catch-all [[...slug]].js instead.

Solution

1. Step 1: Understand catch-all vs optional catch-all

   Catch-all [...slug].js requires at least one path part; it does not match the base path alone.

2. Step 2: Identify fix for base path requests

   To handle base path /api with no extra parts, use optional catch-all [[...slug]].js.

3. Final Answer:

   Catch-all routes require at least one path segment; use optional catch-all [[...slug]].js instead. -> Option D

4. Quick Check:

   Catch-all needs path parts; optional catch-all handles empty [OK]

Hint: Use [[...name]].js for optional catch-all including empty path [OK]

Common Mistakes:

• Expecting catch-all to match empty path
• Misnaming the file without brackets
• Ignoring export of handler function

5. You want to create a catch-all API route that returns a JSON object with keys for each path part and their index, for example, for /api/a/b/c it returns {"0": "a", "1": "b", "2": "c"}. Which handler code inside pages/api/[...parts].js achieves this?

hard

A. export default function handler(req, res) {
const obj = {};
req.query.parts.forEach((p, i) => { obj[i] = p; });
res.json(obj);
}

B. export default function handler(req, res) {
res.json(req.query.parts.join(','));
}

C. export default function handler(req, res) {
res.json({ parts: req.query.parts });
}

D. export default function handler(req, res) {
res.json(req.query.parts.length);
}

Solution

1. Step 1: Understand the input and desired output

   The catch-all parameter parts is an array of path parts. We want to create an object with keys as indices and values as parts.

2. Step 2: Check which code builds the object correctly

   export default function handler(req, res) { const obj = {}; req.query.parts.forEach((p, i) => { obj[i] = p; }); res.json(obj); } loops over req.query.parts and assigns each part to the object with its index as key, then returns it as JSON.

3. Final Answer:

   export default function handler(req, res) { const obj = {}; req.query.parts.forEach((p, i) => { obj[i] = p; }); res.json(obj); } -> Option A

4. Quick Check:

   Loop parts to object with index keys = export default function handler(req, res) { const obj = {}; req.query.parts.forEach((p, i) => { obj[i] = p; }); res.json(obj); } [OK]

Hint: Use forEach to map array parts to object keys [OK]

Common Mistakes:

• Returning array or string instead of object
• Not looping to create object keys
• Returning length instead of parts