[Next.js Tutorial] API Routes: Build Your Backend Quickly and Efficiently

Have you ever dreamed of a world where frontend and backend live harmoniously under one roof, where building a fully functional API is as simple as creating a React component? That dream has come true with API Routes in Next.js, especially with the introduction of the App Router.

In this article, let's explore how Next.js completely transforms web development, allowing you to build powerful, high-performance full-stack applications without leaving the familiar ecosystem.

What are API Routes? Why Should You Care?

Simply put, API Routes are a feature of Next.js that lets you create API endpoints right inside your Next.js project. Instead of setting up a separate backend server (using Express, Spring, Django, etc.), you can write server-side code to handle HTTP requests (GET, POST, PUT, DELETE), interact with databases, authenticate users, and perform any other backend logic.

With the App Router, this architecture is refined and more powerful than ever through a concept called Route Handlers.

Outstanding Benefits:

• All-in-One: Simplifies project architecture. Frontend and backend share the same codebase, build, and deployment process.
• Optimized Performance: API Routes can leverage Serverless Functions when deployed on platforms like Vercel, automatically scaling with traffic and saving costs.
• Great Developer Experience (DX): You still use JavaScript/TypeScript and familiar tools from the React/Next.js ecosystem.
• Security: Your backend code is never sent to the browser, protecting sensitive info like API keys or database connection strings.

Creating Your First API with Route Handlers

In the App Router, creating an API endpoint is more intuitive than ever. Instead of files in the pages/api directory, you create route.js (or route.ts) files inside the app directory.

Directory Structure

To create an endpoint /api/hello, just set up the following structure:

app/
└── api/
    └── hello/
        └── route.js

Writing a Route Handler

Inside route.js, export functions named after HTTP methods.

// In app/api/hello/route.js

// Handler for GET method
export async function GET(request) {
  // Handle logic here
  return new Response('Welcome to my API!', {
    status: 200,
  })
}

// Handler for POST method
export async function POST(request) {
  const body = await request.json() // Read request body
  console.log(body)
  return new Response(
    JSON.stringify({ message: 'Data received', data: body }),
    {
      status: 201, // Created
      headers: {
        'Content-Type': 'application/json',
      },
    },
  )
}

Simple, right? With just a few lines of code, you have an API endpoint /api/hello ready to handle GET and POST requests.

Important Note: Next.js is built on standard Web APIs like Request and Response. This makes your code easily compatible and runnable in different environments, such as Edge Functions.

Advanced Techniques and Real-World Examples

1. Dynamic API Routes: Creating Flexible APIs

Just like dynamic pages, you can create dynamic API routes to handle changing parameters. For example, to get info for a specific product via /api/products/[id].

Directory Structure:

app/
└── api/
    └── products/
        └── [id]/
            └── route.js

Source Code (route.js):

// In app/api/products/[id]/route.js

export async function GET(request, { params }) {
  const productId = params.id // Get 'id' from URL

  // Example: Find product in database
  // const product = await db.products.find(productId);

  return new Response(
    JSON.stringify({ id: productId, name: `Product ${productId}` }),
    {
      status: 200,
      headers: {
        'Content-Type': 'application/json',
      },
    },
  )
}

Now, a request to /api/products/123 will be handled by this handler and params.id will be "123".

2. Handling Requests and Responses

Quick summary:

• Access Query Parameters: const { searchParams } = new URL(request.url)
• Read Headers: const authorization = request.headers.get('authorization')
• Read Cookies: Use cookies() from next/headers.
• Set Headers for Response: new Response(..., { headers: { ... } })
• Set Cookies for Response: new Response(..., { headers: { 'Set-Cookie': '...' } })
• Redirect: Use NextResponse.redirect() from next/server.

Comprehensive Example:

// In app/api/search/route.js
import { NextResponse } from 'next/server'

export async function GET(request) {
  const { searchParams } = new URL(request.url)
  const query = searchParams.get('q') // Get 'q' query param

  if (!query) {
    return new NextResponse(
      JSON.stringify({ error: 'Missing search parameter' }),
      {
        status: 400,
        headers: { 'Content-Type': 'application/json' },
      },
    )
  }

  // Search logic with 'query'
  const results = [`Result 1 for "${query}"`, `Result 2 for "${query}"`]

  return NextResponse.json({ data: results }) // Convenient way to return JSON
}

3. Caching and Revalidating

One of Next.js's greatest strengths is caching. By default, GET requests in Route Handlers are cached. You can control this behavior:

• Disable cache: export const dynamic = 'force-dynamic'
• Revalidate by time:

  export async function GET(request) {
    const res = await fetch('https://api.example.com/data', {
      next: { revalidate: 3600 }, // Revalidate every hour
    })
    const data = await res.json()
    return NextResponse.json(data)
  }
  

This is extremely useful for building high-performance APIs without hitting your data source (database, CMS) on every request.

When Should You Use API Routes?

Most common real-world scenarios:

• Form Handling: Receive data from client-side forms, validate, and save to the database.
• Third-party Communication: Hide API keys by creating your own endpoint to call third-party APIs (Stripe, SendGrid, etc.).
• User Authentication: Handle login, registration, and session management.
• Provide Data for Client Components: Create API endpoints for client components to safely fetch data.
• Build a Complete Backend: For small to medium projects, API Routes can fully replace a separate backend, saving you time and effort.

Conclusion: The Future of Full-Stack Development

API Routes with the App Router are not just a feature; they're a shift in how we think about building web apps. By erasing the boundary between frontend and backend, Next.js empowers developers to create more complete, high-performance, and maintainable products than ever before. Whether you're building a personal blog or a complex e-commerce app, give API Routes a try. You'll be amazed at the speed and convenience they bring.

Now, are you ready to build your own backend right inside Next.js? Start today!