Building APIs With Next.js: A Simple Guide For Developers

Next.js isn't just for building powerful frontend apps—it’s also a full-stack framework. With its latest advancements like the App Router and Route Handlers, you can create backend APIs right within your Next.js app using web-standard Request and Response objects.

In this article, we explore how to build scalable, production-ready APIs using the modern Next.js architecture. Whether you're serving web clients, mobile apps, or third-party services, you'll learn everything from dynamic routing to secure middleware patterns.

---

Getting Started

To create a new Next.js app with API examples included:

Copy
npx create-next-app@latest --api

This scaffolds a project using the App Router with example route.ts files under the app/api/ directory.

---

Why and When to Build APIs with Next.js

Use Next.js for APIs when:

• You want a public API shared across web, mobile, or third-party clients
• You need a proxy or Backend-for-Frontend (BFF) to consolidate microservices
• You're implementing webhooks, custom auth, or backend logic tightly coupled with your frontend

If you only need server-side data fetching for your frontend (without exposing endpoints), consider using Server Components.

---

Creating an API with Route Handlers

In the App Router, route handlers live inside the app/api/ directory.

Example folder structure:

Copy
app/
└── api/
    └── users/
        └── route.ts

Basic API handler:

Copy
export async function GET(request: Request) {
  const users = [{ id: 1, name: 'Alice' }];
  return new Response(JSON.stringify(users), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
}

You can export multiple methods (GET, POST, PUT, etc.) in a single file.

---

Handling Multiple HTTP Methods

Copy
export async function POST(request: Request) {
  const body = await request.json();
  const { name } = body;

  const newUser = { id: Date.now(), name };
  return new Response(JSON.stringify(newUser), {
    status: 201,
    headers: { 'Content-Type': 'application/json' },
  });
}

This allows /api/users to handle both read and write operations from the same file.

---

Working with Web APIs

The App Router uses Web Platform APIs. You receive Request objects and return Response objects.

Query Parameters

Copy
import { NextRequest } from 'next/server';

export function GET(request: NextRequest) {
  const query = request.nextUrl.searchParams.get('q');
  return new Response(JSON.stringify({ query }));
}

Cookies and Headers

Copy
import { cookies, headers } from 'next/headers';

export function GET() {
  const token = cookies().get('token')?.value;
  const referer = headers().get('referer');

  return new Response(JSON.stringify({ token, referer }));
}

---

Dynamic Routes and Catch-All APIs

For routes like /api/users/123:

Copy
app/
└── api/
    └── users/
        └── [id]/
            └── route.ts

Copy
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  return new Response(JSON.stringify({ id: params.id }));
}

Catch-All Routes

Copy
app/api/docs/[...slug]/route.ts

Copy
export async function GET(
  request: Request,
  { params }: { params: { slug: string[] } }
) {
  return new Response(JSON.stringify({ slug: params.slug }));
}

---

API Flow Diagram

---

Proxying External APIs

---

Middleware and Authentication

Reusable auth wrapper:

Usage:

---

Testing and Deployment

Unit Testing Example with Jest

Deployment Tips

---

When to Skip API Endpoints

Use for internal-only data fetching:

---

The Bottom Line!

Building APIs with using the and provides a modern, scalable, and developer-friendly full-stack experience.

✅ Use web-standard and objects
✅ Handle multiple HTTP methods in a single file
✅ Create dynamic, nested, and catch-all routes
✅ Share middleware logic across endpoints
✅ Proxy other APIs or handle webhooks
✅ Test and deploy APIs with confidence

Embrace not just as a frontend tool—but as your complete backend layer too.

export async function GET() {
  const res = await fetch('https://api.example.com/data', {
    headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  });

  const data = await res.json();
  return new Response(JSON.stringify({ ...data, proxy: true }));
}

type Handler = (req: Request) => Promise<Response>;

export function withAuth(handler: Handler): Handler {
  return async (req) => {
    const token = req.headers.get('authorization');
    if (!token || token !== 'Bearer valid-token') {
      return new Response(JSON.stringify({ error: 'Unauthorized' }), {
        status: 401,
      });
    }
    return handler(req);
  };
}

import { withAuth } from '@/lib/with-auth';

async function secretHandler(request: Request) {
  return new Response(JSON.stringify({ secret: '🍕' }));
}

export const GET = withAuth(secretHandler);

import handler from '@/app/api/users/[id]/route';

test('GET user by ID', async () => {
  const request = new Request('http://localhost/api/users/123', {
    method: 'GET',
  });
  const response = await handler(request, { params: { id: '123' } });
  const body = await response.json();

  expect(response.status).toBe(200);
  expect(body).toEqual({ id: '123' });
});

// app/users/page.tsx
export default async function UsersPage() {
  const res = await fetch('https://api.example.com/users');
  const users = await res.json();

  return (
    <ul>
      {users.map((u: any) => (
        <li key={u.id}>{u.name}</li>
      ))}
    </ul>
  );
}