Why Catch-all API routes in NextJS? - Purpose & Use Cases

The Big Idea

Discover how one file can replace dozens and keep your API neat and powerful!

The Scenario

Imagine building an API where you must create a separate file for every possible URL path your app might receive, like /api/user, /api/user/profile, /api/user/profile/settings, and so on.

The Problem

Manually creating many files for each URL path is slow, confusing, and hard to maintain. It's easy to make mistakes and miss paths, leading to broken or inconsistent API behavior.

The Solution

Catch-all API routes let you handle many URL paths with a single file. This means you write one flexible handler that can respond to any nested path, making your code simpler and easier to manage.

Before vs After

✗ Before

pages/api/user.js
pages/api/user/profile.js
pages/api/user/profile/settings.js

✓ After

pages/api/[...slug].js
// One file handles /user, /user/profile, /user/profile/settings, etc.

What It Enables

It enables building scalable APIs that adapt to many URL patterns without extra files or complex routing logic.

Real Life Example

Think of a blog where posts have categories and subcategories. Instead of making a file for each category path, a catch-all route handles all post URLs dynamically.

Key Takeaways

Manually creating many API files is tedious and error-prone.

Catch-all routes let one file handle many URL paths.

This simplifies API code and makes it easier to scale.

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