Route Handler Pattern | Bootspring Docs

Build robust REST APIs using Next.js App Router route handlers with type-safe validation, authentication, and error handling.

Overview#

Route handlers are the foundation of API development in Next.js 13+. They provide a modern, file-based approach to building RESTful endpoints with full support for streaming, caching, and edge runtime.

When to use:

Building REST APIs for external consumers
Handling webhooks from third-party services
Creating public endpoints for your application
Implementing file upload/download endpoints

Key features:

File-based routing in app/api/ directory
Support for all HTTP methods (GET, POST, PUT, PATCH, DELETE)
Built-in request/response helpers
Edge runtime support
Streaming responses

Code Example#

Basic CRUD Route Handler#

// app/api/posts/route.ts
import { prisma } from '@/lib/db'
import { auth } from '@/lib/auth'
import { NextRequest, NextResponse } from 'next/server'
import { z } from 'zod'

const CreatePostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().optional(),
  published: z.boolean().default(false)
})

// GET /api/posts
export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams
  const page = parseInt(searchParams.get('page') ?? '1')
  const limit = parseInt(searchParams.get('limit') ?? '10')

  const posts = await prisma.post.findMany({
    where: { published: true },
    orderBy: { createdAt: 'desc' },
    skip: (page - 1) * limit,
    take: limit,
    include: { author: { select: { name: true } } }
  })

  return NextResponse.json({ posts, page, limit })
}

// POST /api/posts
export async function POST(request: NextRequest) {
  try {
    const { userId } = await auth()
    if (!userId) {
      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
    }

    const body = await request.json()
    const validated = CreatePostSchema.parse(body)

    const post = await prisma.post.create({
      data: { ...validated, authorId: userId }
    })

    return NextResponse.json(post, { status: 201 })
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json({ error: error.errors }, { status: 400 })
    }
    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
  }
}

Dynamic Route Handler#

// app/api/posts/[id]/route.ts
import { prisma } from '@/lib/db'
import { auth } from '@/lib/auth'
import { NextRequest, NextResponse } from 'next/server'

type Params = { params: Promise<{ id: string }> }

// GET /api/posts/:id
export async function GET(request: NextRequest, { params }: Params) {
  const { id } = await params

  const post = await prisma.post.findUnique({
    where: { id },
    include: { author: { select: { name: true, email: true } } }
  })

  if (!post) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 })
  }

  return NextResponse.json(post)
}

// PATCH /api/posts/:id
export async function PATCH(request: NextRequest, { params }: Params) {
  const { userId } = await auth()
  if (!userId) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { id } = await params
  const body = await request.json()

  const post = await prisma.post.findUnique({ where: { id } })
  if (!post) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 })
  }
  if (post.authorId !== userId) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
  }

  const updated = await prisma.post.update({
    where: { id },
    data: body
  })

  return NextResponse.json(updated)
}

// DELETE /api/posts/:id
export async function DELETE(request: NextRequest, { params }: Params) {
  const { userId } = await auth()
  if (!userId) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { id } = await params

  const post = await prisma.post.findUnique({ where: { id } })
  if (!post || post.authorId !== userId) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
  }

  await prisma.post.delete({ where: { id } })

  return new NextResponse(null, { status: 204 })
}

Error Handling Wrapper#

// lib/api-utils.ts
import { NextRequest, NextResponse } from 'next/server'
import { ZodError } from 'zod'

type Handler = (req: NextRequest, context?: any) => Promise<NextResponse>

export function withErrorHandling(handler: Handler): Handler {
  return async (req, context) => {
    try {
      return await handler(req, context)
    } catch (error) {
      console.error('API Error:', error)

      if (error instanceof ZodError) {
        return NextResponse.json(
          { error: 'Validation failed', details: error.errors },
          { status: 400 }
        )
      }

      if (error instanceof Error) {
        if (error.message === 'UNAUTHORIZED') {
          return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
        }
        if (error.message === 'NOT_FOUND') {
          return NextResponse.json({ error: 'Not found' }, { status: 404 })
        }
      }

      return NextResponse.json(
        { error: 'Internal server error' },
        { status: 500 }
      )
    }
  }
}

Usage Instructions#

Create route file: Add a route.ts file in the appropriate app/api/ directory
Export HTTP methods: Export async functions named after HTTP methods (GET, POST, PUT, PATCH, DELETE)
Add validation: Use Zod schemas to validate request bodies
Handle authentication: Check auth state before processing requests
Return appropriate responses: Use NextResponse.json() with proper status codes

Best Practices#

Always validate input - Use Zod or similar library to validate request bodies and query parameters
Implement proper error handling - Return consistent error responses with appropriate status codes
Use authentication middleware - Check auth state at the beginning of protected routes
Keep handlers focused - Each handler should do one thing well
Use TypeScript - Define types for request/response bodies
Log errors - Log server errors for debugging while returning generic messages to clients
Consider rate limiting - Protect endpoints from abuse

Server Action - Alternative for form submissions and mutations
Middleware - Request preprocessing and authentication
Error Handling - Consistent error response formats
Rate Limiting - Protect APIs from abuse