Next.js API Routes vs Route Handlers: What’s the Difference?
Introduction
Building a website with Next.js often involves more than displaying pages. You may also need to retrieve blog posts from a database, accept contact form submissions, authenticate users, or provide data to a frontend application.
These tasks often require an API endpoint.
Next.js offers two approaches for creating API endpoints: API Routes in the Pages Router and Route Handlers in the App Router. Both allow you to process HTTP requests and return responses, but they use different file conventions and programming interfaces.
Understanding Next.js API Routes vs Route Handlers is particularly important if you are starting a new project, learning Next.js, or migrating an older application.
The central difference is straightforward: API Routes use the pages/api directory and a default-exported handler, while Route Handlers use route.js or route.ts files in the app directory and named exports for HTTP methods. Both approaches remain supported in their respective routers.
Let’s explore how they work, compare their features, and see which approach makes sense for your project.
What Are Next.js API Routes?
Next.js API Routes let you create server-side API endpoints inside the Pages Router.
You define these endpoints by placing JavaScript or TypeScript files inside the pages/api directory. Next.js maps those files to URLs beginning with /api.
For example, this file:
pages/
└── api/
└── hello.ts
creates the endpoint:
/api/hello
When a client sends a request to that URL, Next.js executes the corresponding handler on the server and returns a response.
How API Routes work
A Pages Router API endpoint typically uses two objects:
- req — contains information about the incoming request.
- res — provides methods for sending the response.
Here is a simple TypeScript example.
// pages/api/hello.ts
import type {
NextApiRequest,
NextApiResponse
} from “next”;
export default function handler(
req: NextApiRequest,
res: NextApiResponse
) {
res.status(200).json({
message: “Hello from Next.js!”
});
}
In this example:
- A browser or application requests /api/hello.
- Next.js executes the handler function.
- The server responds with a JSON object and HTTP status code 200.
- The client receives the response.
The response body looks like this:
{
“message”: “Hello from Next.js!”
}
This approach is documented in the official Next.js API Routes documentation.
Handling different HTTP methods
A single API Route can process different request methods by checking req.method.
// pages/api/message.ts
import type {
NextApiRequest,
NextApiResponse
} from “next”;
export default function handler(
req: NextApiRequest,
res: NextApiResponse
) {
if (req.method === “GET”) {
return res.status(200).json({
message: “Here is your data”
});
}
if (req.method === “POST”) {
return res.status(201).json({
message: “Your data was received”
});
}
return res.status(405).json({
error: “Method not allowed”
});
}
Here, the same endpoint responds differently depending on the incoming HTTP method.
For beginners, API Routes are useful when maintaining an existing application built around the Pages Router.
What Are Next.js Route Handlers?
Route Handlers are the App Router’s approach to creating custom HTTP endpoints.
Instead of placing endpoint files inside pages/api, you create a route.js or route.ts file inside the app directory.
For example:
app/
└── api/
└── hello/
└── route.ts
This creates the /api/hello endpoint.
Route Handlers use the standard Web Request and Response APIs. They also support Next.js-specific extensions, including NextRequest and NextResponse, when additional functionality is needed.
How Route Handlers work
Here is a basic TypeScript example.
// app/api/hello/route.ts
export async function GET() {
return Response.json({
message: “Hello from Next.js!”
});
}
When a client sends a GET request to /api/hello, Next.js calls the exported GET function and returns the JSON response.
Notice the main differences from the previous example:
- The file is named route.ts.
- The handler is a named export called GET.
- The response uses the Web Response API.
- You do not need to check req.method manually for this GET handler.
Handling multiple HTTP methods
Route Handlers let you export separate functions for the HTTP methods an endpoint supports.
// app/api/message/route.ts
export async function GET() {
return Response.json({
message: “Here is your data”
});
}
export async function POST(request: Request) {
const body = await request.json();
return Response.json(
{
message: “Your data was received”,
data: body
},
{
status: 201
}
);
}
The GET function handles GET requests, while POST processes POST requests and reads the submitted JSON body.
The example echoes the submitted data; a production endpoint would normally validate it before saving it or performing another action.
Route Handlers support GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.
For more details, see the official Next.js Route Handlers guide.
Next.js API Routes vs Route Handlers: Key Differences
The following table summarizes the most important differences.
| Feature | API Routes | Route Handlers |
| Router | Pages Router | App Router |
| Directory | pages/api/ | app/ |
| File naming | Usually a .js or .ts filename | route.js or route.ts |
| Handler style | Default-exported function | Named HTTP method exports |
| Request interface | NextApiRequest | Web Request or NextRequest |
| Response interface | NextApiResponse | Web Response or NextResponse |
| HTTP method handling | Check req.method | Export a function per method |
| Request body | Usually available as parsed req.body | Read with methods such as request.json() |
| Dynamic endpoints | Supported | Supported |
| Caching | Depends on implementation and configuration | Route Handler caching and prerendering rules apply |
| Static export | API Routes are not supported | Compatible Route Handlers can be used |
| Existing project compatibility | Suitable for Pages Router projects | Suitable for App Router projects |
The comparison reflects the documented conventions of the two routers. Static export compatibility and caching behavior depend on the route’s implementation and configuration.
The biggest difference: file structure and handler design
An API Route might look like this:
pages/api/products.ts
A Route Handler might look like this:
app/api/products/route.ts
Both can expose the URL /api/products, but they use different conventions internally.
This distinction is more important than the terminology. Route Handlers are not simply a new name for API Routes; they are the App Router’s equivalent API mechanism, designed around Web Request and Response APIs.
How to Create the Same API Using Both Approaches
Imagine you are building a blog and want an endpoint that returns a list of published articles.
For example, a frontend might request /api/posts to display recent posts.
Let’s implement a simplified version using each approach.
Example 1: Create an API Route
Create this file:
pages/api/posts.ts
import type {
NextApiRequest,
NextApiResponse
} from “next”;
const posts = [
{
id: 1,
title: “Introduction to SEO”
},
{
id: 2,
title: “Understanding Next.js”
}
];
export default function handler(
req: NextApiRequest,
res: NextApiResponse
) {
if (req.method !== “GET”) {
return res.status(405).json({
error: “Method not allowed”
});
}
return res.status(200).json(posts);
}
The endpoint is available at /api/posts.
When a client makes a GET request, the server returns the sample article data.
Example 2: Create a Route Handler
Create this file:
app/api/posts/route.ts
const posts = [
{
id: 1,
title: “Introduction to SEO”
},
{
id: 2,
title: “Understanding Next.js”
}
];
export async function GET() {
return Response.json(posts);
}
This also exposes /api/posts and returns the same sample data.
The Route Handler is shorter because it handles GET requests through a dedicated exported function instead of checking the method inside a shared handler.
Important: These are alternative implementations of the same endpoint. Do not create both files for the same URL in the same application, as they can cause a routing conflict.
When Should You Use API Routes?
API Routes remain useful in several situations.
-
You already have a Pages Router application
If your project uses the pages directory and its existing API endpoints work correctly, you can continue using them.
There is no need to migrate an application solely because Route Handlers are available.
-
You maintain an older codebase
Existing API Routes may depend on NextApiRequest, NextApiResponse, parsed request bodies, or API-specific configuration.
Keeping these endpoints can avoid unnecessary changes and regression risks.
-
You need established Pages Router behavior
API Routes have their own request helpers and configuration options, including body-parser settings and response-size warnings. These can be relevant to existing integrations.
Before changing an endpoint, consider how its current implementation handles authentication, errors, request parsing, and deployment.
When Should You Use Route Handlers?
Route Handlers are a natural choice for many new App Router projects.
-
You are building a new Next.js application with the App Router
If your application uses the app directory, Route Handlers provide the matching convention for creating HTTP endpoints.
You do not need to add a separate Pages Router API directory simply to expose backend functionality.
-
You prefer standard Web APIs
Route Handlers use familiar web interfaces such as:
- Request
- Response
- request.json()
- request.text()
- request.headers
This can make concepts more transferable to other JavaScript environments that use Web APIs.
-
You need to support several HTTP methods
Separate exported functions make the intended behavior easier to identify.
For example, a product endpoint might export GET to retrieve products and POST to create a product.
-
You are building webhook or integration endpoints
Route Handlers can receive requests from external services, including webhook events, provided the endpoint is deployed in a compatible environment and correctly validates incoming requests.
For example, a payment service might send a POST request when a payment status changes. Your Route Handler can verify the event, process it, and return an appropriate HTTP status.
Remember that neither routing approach automatically makes an endpoint secure. Authentication, authorization, validation, and webhook signature verification still require deliberate implementation.
Do Route Handlers Perform Better Than API Routes?
A common question is whether Next.js Route Handlers are faster than API Routes.
There is no universal performance winner. Response time depends on several factors, including the work performed by the endpoint, database latency, external API calls, runtime selection, caching, and hosting configuration.
Route Handlers use a different programming interface, but that does not automatically make every request faster.
Consider two examples:
- API Route: Fetches 500 blog posts from a database for every request.
- Route Handler: Fetches the same posts but uses an appropriate cache for data that can safely be reused.
The second endpoint may respond faster because of its caching strategy, not simply because it uses a Route Handler.
When evaluating performance, measure actual response times and check database queries, cache behavior, server logs, and hosting limits.
For a beginner, the practical recommendation is to choose the routing approach that fits your project first, then optimize based on measurements.
Caching in Next.js API Routes vs Route Handlers
Caching is one of the areas where developers need to understand the behavior of their chosen implementation.
API Routes and caching
API Routes use the Pages Router’s request and response model. Their responses can be influenced by HTTP caching headers, hosting infrastructure, and how the endpoint is implemented.
For example, a public endpoint returning an article category list could send a cache-control header:
res.setHeader(
“Cache-Control”,
“public, max-age=60”
);
This instructs compatible caches to treat the response as fresh for 60 seconds. The actual caching behavior still depends on the client and any intermediary cache.
Do not use public caching for responses containing private user information.
Route Handlers and caching
Route Handlers have their own caching and prerendering rules.
In current Next.js documentation, Route Handlers are not cached by default, although GET responses can be configured for caching. When Cache Components are enabled, GET handlers follow that model’s rules, including request-time execution and prerendering where appropriate.
For example, in a compatible configuration, a GET Route Handler can use a static route configuration:
// app/api/site-info/route.ts
export const dynamic = “force-static”;
export async function GET() {
return Response.json({
site: “SEO Insights”,
category: “Digital Marketing”
});
}
This example is intended for data that can safely be served as a static response. It is not appropriate for user-specific or frequently changing information without a suitable freshness strategy.
Best practice: Verify the caching behavior against your installed Next.js version and configuration. Do not assume every GET request is automatically cached.
Can You Use API Routes and Route Handlers in the Same Project?
Yes. Next.js supports both the Pages Router and App Router in the same application, allowing gradual migration and mixed routing structures.
For example, an application could contain:
my-next-app/
├── pages/
│ └── api/
│ └── legacy-data.ts
│
└── app/
└── api/
└── posts/
└── route.ts
In this structure:
- /api/legacy-data is served by the Pages Router API Route.
- /api/posts is served by the App Router Route Handler.
This arrangement can be useful when a team gradually updates an older application.
However, do not define competing handlers for the same endpoint. Keep the routing structure clear so developers know which file owns each URL.
How to Migrate From API Routes to Route Handlers
If you already use API Routes, you can migrate individual endpoints when there is a clear benefit.
You do not have to rewrite your entire backend at once.
Step 1: Identify the existing endpoint
Suppose your current file is:
pages/api/posts.ts
It exposes /api/posts.
First, document its supported HTTP methods, request format, authentication requirements, response structure, and error handling.
Step 2: Create the Route Handler file
Create the corresponding file in the App Router:
app/api/posts/route.ts
Step 3: Replace the handler convention
An API Route might use:
if (req.method === “GET”) {
return res.status(200).json(posts);
}
A Route Handler can instead use:
export async function GET() {
return Response.json(posts);
}
This illustrates the basic conversion. A production migration must also account for request parsing, headers, status codes, cookies, authentication, and error handling.
Step 4: Update request and response handling
API Routes commonly access query parameters through req.query and parsed bodies through req.body.
With a Route Handler, query parameters can be read from the request URL:
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const category = searchParams.get(“category”);
return Response.json({
category
});
}
For a JSON request body, use:
const body = await request.json();
Remember that request bodies are streams and should not be read repeatedly without an appropriate strategy.
Step 5: Test before replacing the old endpoint
Check that the migrated endpoint preserves:
- HTTP status codes and response formats.
- Authentication and authorization rules.
- Input validation and error handling.
- Query parameters and dynamic route parameters.
- Caching behavior and relevant response headers.
- Database operations and external integrations.
Finally, test the new endpoint in a staging environment before switching production traffic.
For additional guidance, consult the official Next.js App Router migration guide.
Common Mistakes Beginners Should Avoid
-
Putting a Route Handler in the wrong directory
A file named route.ts inside pages/api does not become an App Router Route Handler.
Use the correct conventions:
- API Route: pages/api/example.ts
- Route Handler: app/api/example/route.ts
-
Using a default export for a Route Handler
A Route Handler expects named exports for supported HTTP methods.
Incorrect:
export default function handler() {
// …
}
Correct:
export async function GET() {
return Response.json({
message: “Success”
});
}
-
Assuming Route Handlers are always cached
They are not automatically cached in every configuration. Understand the installed Next.js version and the behavior of the endpoint before relying on cached responses.
-
Exposing secrets in API responses
Never return database credentials, private API keys, authentication tokens, or sensitive environment variables to untrusted clients.
Keep secrets on the server and return only the information the client needs.
-
Forgetting input validation
An endpoint that accepts a user-submitted email address, article ID, or product price should validate the input before processing it.
TypeScript types alone do not validate incoming JSON at runtime.
-
Ignoring authentication and authorization
A publicly accessible endpoint is not automatically safe for private operations.
For example, an endpoint that updates a blog post should verify that the requester has permission to modify that post. Protect sensitive endpoints against unauthorized access, abuse, and inappropriate data exposure.
-
Treating CORS as authentication
CORS controls which browser origins can access certain cross-origin responses. It is not a replacement for authentication or authorization.
Pages Router API Routes are same-origin by default unless CORS behavior is configured. Route Handlers also require deliberate CORS configuration when cross-origin browser access is needed.
Do You Need an API Endpoint at All?
There is one more important consideration: not every application needs a separate API endpoint for its own data.
In the App Router, a Server Component can often retrieve data directly from a database or another service on the server.
For example, a blog page can query its article database directly instead of making an HTTP request to its own /api/posts endpoint.
This can avoid an unnecessary network round trip and simplify the application architecture.
A Route Handler is more useful when you need a genuine HTTP interface, such as:
- An endpoint consumed by a mobile application.
- A webhook receiver.
- A public or authenticated REST API.
- A browser form submission that needs an HTTP response.
- An integration with an external service.
Next.js also offers Server Functions and Server Actions for certain server-side operations initiated by the application. These serve different purposes and should not be treated as automatic replacements for every API endpoint. See the official Building APIs with Next.js guide.
Useful Tools and Resources
The following official resources can help you implement and troubleshoot either approach.
Next.js API Routes documentation
Learn about request helpers, response methods, dynamic API endpoints, and configuration.
Next.js Route Handlers documentation
Explore file conventions, supported HTTP methods, request handling, and caching.
Understand the standard Web Request interface used by Route Handlers.
Key Takeaways
- API Routes belong to the Pages Router: Create them in pages/api and use a default-exported handler.
- Route Handlers belong to the App Router: Create a route.ts or route.js file and export functions such as GET and POST.
- Both can build APIs: They can return JSON, validate requests, interact with databases, and integrate with external services.
- Choose according to your project: Route Handlers are a natural fit for new App Router endpoints, while API Routes remain suitable for existing Pages Router applications.
- Caching requires attention: Understand your route configuration, response headers, and Next.js caching rules before relying on cached data.
- Security matters more than syntax: Validate input, protect secrets, and implement authentication and authorization where needed.
- Not every operation needs an API: App Router Server Components can often retrieve server-side data directly without an internal HTTP request.
FAQ
-
What is the difference between Next.js API Routes and Route Handlers?
API Routes are defined in the pages/api directory and use a handler function with Next.js request and response objects. Route Handlers are defined using route.js or route.ts files in the app directory and use named HTTP method exports with Web Request and Response APIs.
-
Are Next.js Route Handlers replacing API Routes?
Route Handlers are the equivalent API mechanism for the App Router. API Routes remain supported in the Pages Router, so existing projects can continue using them without an immediate migration.
-
Which is better for a new Next.js project: API Routes or Route Handlers?
If you are building API endpoints in a new App Router project, Route Handlers are the natural choice. If you are working with a Pages Router application, API Routes remain appropriate. Your application’s architecture and requirements should guide the decision.
-
Can I use API Routes and Route Handlers together?
Yes. A Next.js application can contain both pages and app routing structures. You can use API Routes for existing endpoints and Route Handlers for new ones, provided you avoid conflicting route definitions.
-
Are Next.js Route Handlers faster than API Routes?
Not necessarily. Performance depends on the implementation, database operations, external services, caching, runtime, and deployment environment. Benchmark your actual endpoints rather than assuming one approach is always faster.
-
Can Route Handlers connect to a database?
Yes. Route Handlers can query a database using an appropriate server-side database client or ORM. Keep credentials in server-side environment variables, validate inputs, and enforce authorization before accessing protected data.
-
How do I handle GET and POST requests in Next.js Route Handlers?
Export a separate asynchronous function for each method you need. For example, use GET() to retrieve data and POST(request) to process submitted data. Read JSON using await request.json() and return a response with Response.json().
-
Should I migrate existing API Routes to Route Handlers?
Migration is optional. Consider it when adopting the App Router, simplifying an endpoint, or aligning your code with the newer routing conventions. Test authentication, request parsing, status codes, caching, and integrations before replacing a working endpoint.
Conclusion
The main difference between Next.js API Routes and Route Handlers is the routing system and the way each handles HTTP requests.
API Routes use the Pages Router’s handler-based approach, while Route Handlers use the App Router’s standard Web Request and Response interfaces.
Neither approach is automatically superior in every situation. For a new App Router project, start with Route Handlers when you need HTTP endpoints. For an existing Pages Router project, continue using API Routes unless there is a practical reason to migrate.
Your next step: Create a simple /api/hello endpoint in the router your project already uses. Test the response, experiment with GET and POST requests, and then build on that foundation with validation, error handling, and secure database access.
For More Articles on Next.js:
- Next.js SEO: Complete Guide for Developers
- Next.js PostgreSQL : How to Connect PostgreSQL to Next.js: Step-by-Step Tutorial
- Next.js Metadata API: Complete SEO Guide to Titles, Descriptions and Open Graph
- Next.js Sitemap and Robots.txt: Complete SEO Configuration Guide
- Next.js Structured Data: How to Add JSON-LD Schema Markup
- Next.js Core Web Vitals: How to Improve LCP, INP and CLS
- Next.js Image Optimization: Complete Guide to Faster Websites
- Next.js 16: What’s New, Features & How to Get Started – 2026
- Next.js Server Components vs Client Components: Complete Guide (2026)
- Next.js App Router vs Pages Router: Key Differences (2026)