Catch-all API routes in NextJS - Deep Dive

Overview - Catch-all API routes

What is it?

Catch-all API routes in Next.js are special API route files that handle multiple URL paths using a single file. They capture all requests that match a certain pattern, including nested paths, so you don't need to create many separate files. This helps organize your API endpoints more efficiently. They use square brackets with three dots, like [...slug].js, to catch all matching routes.

Why it matters

Without catch-all API routes, you would need to create a separate file for every possible API path, which can become messy and hard to maintain. Catch-all routes let you handle many related API requests in one place, making your code cleaner and easier to update. This saves time and reduces errors when your API needs to support dynamic or nested paths.

Where it fits

Before learning catch-all API routes, you should understand basic Next.js API routes and how file-based routing works. After mastering catch-all routes, you can explore dynamic API routes with optional catch-all segments and advanced request handling techniques.

Mental Model

Core Idea

A catch-all API route is like a single mailbox that collects all letters sent to any address under a certain street, so you don't need a mailbox for every house.

Think of it like...

Imagine a large apartment building with one mailroom that receives mail for all apartments inside. Instead of having a mailbox for each apartment, all mail goes to this one room, and the mailroom staff sorts it based on apartment numbers. Similarly, a catch-all API route receives all requests under a path and decides how to handle each.

API Routes Folder
└── api
    ├── users.js          (handles /api/users)
    ├── posts.js          (handles /api/posts)
    └── [...slug].js      (handles /api/anything/else/here)

Request Paths:
/api/users           → users.js
/api/posts           → posts.js
/api/products/123    → [...slug].js with slug=["products","123"]
/api/a/b/c           → [...slug].js with slug=["a","b","c"]

Build-Up - 7 Steps

1

Foundation

Basic Next.js API Routes

Concept: Learn how Next.js uses files in the api folder to create API endpoints.

In Next.js, any JavaScript file inside the 'pages/api' folder becomes an API endpoint. For example, 'pages/api/hello.js' handles requests to '/api/hello'. Each file exports a function that receives request and response objects to handle HTTP methods.

Result

You can create simple API endpoints by adding files, and Next.js automatically routes requests to them.

Understanding file-based routing is essential because catch-all routes build on this concept by matching multiple paths with one file.

2

Foundation

Dynamic API Routes with Parameters

Concept: Introduce dynamic segments in API routes using square brackets to capture parts of the URL.

You can create dynamic API routes by naming files with square brackets, like '[id].js'. This file handles requests like '/api/user/123', where '123' is captured as a parameter. Inside the handler, you access it via 'req.query.id'.

Result

Dynamic routes let you handle variable parts of the URL without creating many files.

Knowing how to capture URL parameters prepares you to understand how catch-all routes capture multiple segments.

3

Intermediate

Catch-all API Route Syntax

🤔Before reading on: do you think catch-all routes capture one segment or multiple URL segments? Commit to your answer.

Concept: Catch-all routes use three dots inside square brackets to capture all remaining URL segments as an array.

To catch multiple URL parts, name the API file '[...slug].js'. This matches any path under that folder, like '/api/a', '/api/a/b', or '/api/a/b/c'. Inside the handler, 'req.query.slug' is an array of all captured segments.

Result

One file can handle many nested API paths, simplifying route management.

Understanding that catch-all routes capture multiple segments as an array helps you design flexible APIs that adapt to many URL shapes.

4

Intermediate

Handling Requests in Catch-all Routes

🤔Before reading on: do you think you must manually parse the array of segments or Next.js provides it ready? Commit to your answer.

Concept: Next.js automatically parses the URL segments into an array accessible via 'req.query'. You can use this array to decide how to respond.

Inside '[...slug].js', you get 'req.query.slug' as an array like ['products', '123']. You can use conditions or switch statements to handle different paths. For example, if slug[0] is 'products', you might fetch product data.

Result

You can write flexible logic to serve many API endpoints from one file.

Knowing that Next.js parses segments for you lets you focus on business logic instead of URL parsing.

5

Intermediate

Optional Catch-all API Routes

🤔Before reading on: do you think optional catch-all routes match URLs with zero segments or always at least one? Commit to your answer.

Concept: Optional catch-all routes use double square brackets with three dots to match zero or more segments, including the base path itself.

Naming a file '[[...slug]].js' matches '/api', '/api/a', '/api/a/b', etc. If no segments are present, 'req.query.slug' is undefined or an empty array. This lets you handle the base API path and nested paths in one file.

Result

You can create a single API route that handles both the root and nested paths.

Understanding optional catch-all routes helps you build APIs that gracefully handle requests with or without extra path segments.

6

Advanced

Performance and Caching Considerations

🤔Before reading on: do you think catch-all routes always perform slower than specific routes? Commit to your answer.

Concept: Catch-all routes can impact performance if they handle many complex paths, but proper caching and logic can mitigate this.

Because catch-all routes handle many paths, they might do more work per request. Using caching headers, memoization, or splitting logic inside the handler can improve speed. Also, Next.js matches specific routes before catch-all, so specific routes are faster.

Result

You can optimize catch-all routes to perform well even with many requests.

Knowing the tradeoffs of catch-all routes helps you balance flexibility and performance in production.

7

Expert

Internal Routing Priority and Edge Cases

🤔Before reading on: do you think catch-all routes override specific API routes or vice versa? Commit to your answer.

Concept: Next.js uses a routing priority system where specific routes take precedence over catch-all routes, affecting how requests are matched.

When a request matches both a specific route and a catch-all route, Next.js chooses the specific route first. This means you can have '[id].js' and '[...slug].js' coexist without conflict. However, edge cases arise when optional catch-all routes overlap with other dynamic routes, requiring careful file naming and testing.

Result

You can design route files to avoid conflicts and unexpected behavior.

Understanding routing priority prevents bugs where requests go to the wrong handler and helps you organize API routes cleanly.

Under the Hood

Next.js uses the file system to map API route files to URL paths. When a request comes in, the server checks for the most specific matching file. Catch-all routes with '[...slug].js' match any path segments not matched by more specific files. The segments are parsed into an array and passed as query parameters. This routing happens at runtime on the server side, allowing dynamic handling of requests.

Why designed this way?

This design leverages the simplicity of file-based routing while providing flexibility for complex URL structures. It avoids the need for manual route configuration files, reducing developer overhead. The catch-all syntax was introduced to handle nested and dynamic paths elegantly, replacing older, more verbose patterns.

Request URL
   ↓
┌─────────────────────────────┐
│ Next.js API Route Matcher    │
├─────────────────────────────┤
│ 1. Check exact file match    │
│ 2. Check dynamic [param].js  │
│ 3. Check catch-all [...slug] │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│ Route Handler Function       │
│ Receives req.query.slug[]    │
│ Processes request accordingly│
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do catch-all API routes capture only one URL segment or multiple? Commit to your answer.

Common Belief: Catch-all API routes only capture one segment of the URL, like dynamic routes.

Reality: Catch-all API routes capture all remaining URL segments as an array, allowing handling of nested paths.

Why it matters: Believing they capture only one segment leads to incorrect route handling and bugs when nested paths are requested.

Quick: Can catch-all routes override specific API routes? Commit to yes or no.

Common Belief: Catch-all API routes override specific API routes if they match the path pattern.

Reality: Next.js prioritizes specific routes over catch-all routes, so specific routes handle matching requests first.

Why it matters: Misunderstanding this can cause confusion when debugging why a specific route is not called.

Quick: Do optional catch-all routes require at least one URL segment? Commit to yes or no.

Common Belief: Optional catch-all routes only match URLs with at least one segment after the base path.

Reality: Optional catch-all routes match zero or more segments, including the base path itself.

Why it matters: This misconception can cause developers to miss handling the base API path in their catch-all route.

Quick: Are catch-all API routes always slower than specific routes? Commit to yes or no.

Common Belief: Catch-all API routes are always slower because they handle more paths.

Reality: While catch-all routes can be more complex, Next.js routing prioritizes specific routes first, and performance depends on handler logic and caching, not just route type.

Why it matters: Assuming catch-all routes are always slow may lead to premature optimization or unnecessary route splitting.

Expert Zone

1

Catch-all routes can coexist with dynamic and specific routes without conflict due to Next.js routing priority rules.

2

Optional catch-all routes return 'undefined' for the slug parameter when no segments are present, requiring careful null checks.

3

Using catch-all routes in middleware or edge functions requires understanding of deployment environment limitations and cold start impacts.

When NOT to use

Avoid catch-all API routes when your API paths are simple and fixed, as specific routes are clearer and easier to maintain. For very large APIs, consider using a dedicated backend framework or microservices to handle complex routing and scaling.

Production Patterns

In production, catch-all API routes are often used for proxying requests, handling CMS content paths, or building RESTful APIs with nested resources. Developers combine catch-all routes with authentication middleware and caching strategies to optimize performance and security.

Connections

RESTful API Design

Catch-all routes help implement flexible RESTful endpoints with nested resources.

Understanding catch-all routes clarifies how to design APIs that reflect resource hierarchies without excessive route files.

File System Routing

Catch-all routes extend the file system routing pattern by capturing multiple path segments.

Knowing catch-all routes deepens understanding of how file names map to URL structures in modern web frameworks.

Event Delegation in JavaScript

Catch-all routes act like event delegation by handling many events (requests) through one handler.

This connection shows how one handler can efficiently manage many cases, reducing code duplication.

Common Pitfalls

#1 Assuming 'req.query.slug' is always defined and an array.

Wrong approach:

export default function handler(req, res) {
const segments = req.query.slug;
if (segments.length === 0) {
res.status(400).json({ error: 'No segments' });
} else {
res.status(200).json({ segments });
}
}

Correct approach:

export default function handler(req, res) {
const segments = req.query.slug || [];
if (segments.length === 0) {
res.status(400).json({ error: 'No segments' });
} else {
res.status(200).json({ segments });
}
}

Root cause:

Optional catch-all routes can have 'slug' undefined when no segments exist, so failing to check causes runtime errors.

#2 Creating a catch-all route that unintentionally overrides specific routes.

Wrong approach:

Only having '[...slug].js' without specific files for known paths, expecting specific routes to work.

Correct approach:

Create specific route files like 'users.js' for '/api/users' and use '[...slug].js' only for unmatched paths.

Root cause:

Not understanding Next.js routing priority leads to unexpected route handling and bugs.

#3 Using catch-all routes for very simple APIs with fixed paths.

Wrong approach:

Using '[...slug].js' to handle '/api/users' and '/api/posts' instead of separate files.

Correct approach:

Create 'users.js' and 'posts.js' files for fixed paths to keep code clear and maintainable.

Root cause:

Overusing catch-all routes complicates code unnecessarily and reduces clarity.

Key Takeaways

Catch-all API routes let you handle many nested URL paths with one file, capturing all segments as an array.

Next.js prioritizes specific routes over catch-all routes, so you can mix both without conflicts.

Optional catch-all routes match zero or more segments, including the base path, so always check for undefined parameters.

Using catch-all routes wisely simplifies API structure but overusing them can reduce code clarity and performance.

Understanding routing priority and parameter parsing is key to building flexible and maintainable Next.js APIs.