tomevault-io Next.js API Routes Skill
Patterns for building API routes in Next.js App Router.
Route Handlers
Basic Route Handler
// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server'
export async function GET(request: NextRequest) {
const users = await db.user.findMany()
return NextResponse.json(users)
}
export async function POST(request: NextRequest) {
const body = await request.json()
const user = await db.user.create({ data: body })
return NextResponse.json(user, { status: 201 })
}
Dynamic Routes
// app/api/users/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server'
export async function GET(
request: NextRequest,
{ params }: { params: { id: string } }
) {
const user = await db.user.findUnique({
where: { id: params.id },
})
if (!user) {
return NextResponse.json(
{ error: 'User not found' },
{ status: 404 }
)
}
return NextResponse.json(user)
}
export async function PUT(
request: NextRequest,
{ params }: { params: { id: string } }
) {
const body = await request.json()
const user = await db.user.update({
where: { id: params.id },
data: body,
})
return NextResponse.json(user)
}
export async function DELETE(
request: NextRequest,
{ params }: { params: { id: string } }
) {
await db.user.delete({ where: { id: params.id } })
return new NextResponse(null, { status: 204 })
}
Request Handling
Query Parameters
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 search = searchParams.get('search') || ''
const users = await db.user.findMany({
where: {
name: { contains: search, mode: 'insensitive' },
},
skip: (page - 1) * limit,
take: limit,
})
const total = await db.user.count({
where: {
name: { contains: search, mode: 'insensitive' },
},
})
return NextResponse.json({
data: users,
pagination: {
page,
limit,
total,
totalPages: Math.ceil(total / limit),
},
})
}
Headers
export async function GET(request: NextRequest) {
// Read headers
const authHeader = request.headers.get('authorization')
const contentType = request.headers.get('content-type')
// Set response headers
return NextResponse.json(
{ data: 'example' },
{
headers: {
'Cache-Control': 'max-age=3600',
'X-Custom-Header': 'value',
},
}
)
}
Cookies
import { cookies } from 'next/headers'
export async function GET() {
const cookieStore = cookies()
const token = cookieStore.get('token')
return NextResponse.json({ token: token?.value })
}
export async function POST(request: NextRequest) {
const response = NextResponse.json({ success: true })
// Set cookie
response.cookies.set('token', 'abc123', {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
maxAge: 60 * 60 * 24 * 7, // 1 week
})
return response
}
Request Body
// JSON body
export async function POST(request: NextRequest) {
const body = await request.json()
return NextResponse.json(body)
}
// Form data
export async function POST(request: NextRequest) {
const formData = await request.formData()
const name = formData.get('name')
const file = formData.get('file') as File
return NextResponse.json({ name, fileName: file.name })
}
// Text body
export async function POST(request: NextRequest) {
const text = await request.text()
return NextResponse.json({ text })
}
Response Types
JSON Response
export async function GET() {
return NextResponse.json({
success: true,
data: { message: 'Hello' },
})
}
Streaming Response
export async function GET() {
const encoder = new TextEncoder()
const stream = new ReadableStream({
async start(controller) {
for (let i = 0; i < 10; i++) {
controller.enqueue(encoder.encode(`data: ${i}\n\n`))
await new Promise((resolve) => setTimeout(resolve, 1000))
}
controller.close()
},
})
return new Response(stream, {
headers: {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
'Connection': 'keep-alive',
},
})
}
File Download
export async function GET() {
const file = await readFile('./files/document.pdf')
return new NextResponse(file, {
headers: {
'Content-Type': 'application/pdf',
'Content-Disposition': 'attachment; filename="document.pdf"',
},
})
}
Redirect
import { redirect } from 'next/navigation'
export async function GET() {
redirect('/new-location')
}
// Or with NextResponse
export async function GET() {
return NextResponse.redirect(new URL('/new-location', request.url))
}
Error Handling
Structured Errors
class ApiError extends Error {
constructor(
public statusCode: number,
public code: string,
message: string
) {
super(message)
}
}
export async function GET(
request: NextRequest,
{ params }: { params: { id: string } }
) {
try {
const user = await db.user.findUnique({
where: { id: params.id },
})
if (!user) {
throw new ApiError(404, 'USER_NOT_FOUND', 'User not found')
}
return NextResponse.json(user)
} catch (error) {
if (error instanceof ApiError) {
return NextResponse.json(
{ error: { code: error.code, message: error.message } },
{ status: error.statusCode }
)
}
console.error('Unexpected error:', error)
return NextResponse.json(
{ error: { code: 'INTERNAL_ERROR', message: 'Internal server error' } },
{ status: 500 }
)
}
}
Authentication
JWT Verification
import { jwtVerify } from 'jose'
async function verifyAuth(request: NextRequest) {
const token = request.headers.get('authorization')?.replace('Bearer ', '')
if (!token) {
return null
}
try {
const { payload } = await jwtVerify(
token,
new TextEncoder().encode(process.env.JWT_SECRET)
)
return payload
} catch {
return null
}
}
export async function GET(request: NextRequest) {
const user = await verifyAuth(request)
if (!user) {
return NextResponse.json(
{ error: 'Unauthorized' },
{ status: 401 }
)
}
return NextResponse.json({ user })
}
Middleware Helper
// lib/api-auth.ts
export function withAuth(
handler: (
request: NextRequest,
context: { params: Record<string, string>; user: User }
) => Promise<NextResponse>
) {
return async (
request: NextRequest,
context: { params: Record<string, string> }
) => {
const user = await verifyAuth(request)
if (!user) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
}
return handler(request, { ...context, user })
}
}
// Usage
export const GET = withAuth(async (request, { params, user }) => {
// user is available here
return NextResponse.json({ user })
})
Validation
With Zod
import { z } from 'zod'
const createUserSchema = z.object({
name: z.string().min(1).max(100),
email: z.string().email(),
age: z.number().int().positive().optional(),
})
export async function POST(request: NextRequest) {
const body = await request.json()
const result = createUserSchema.safeParse(body)
if (!result.success) {
return NextResponse.json(
{
error: 'Validation failed',
details: result.error.flatten().fieldErrors,
},
{ status: 400 }
)
}
const user = await db.user.create({ data: result.data })
return NextResponse.json(user, { status: 201 })
}
Caching
Static Routes
// Force static (default for GET without dynamic data)
export const dynamic = 'force-static'
export async function GET() {
return NextResponse.json({ message: 'Static response' })
}
Dynamic Routes
export const dynamic = 'force-dynamic'
export async function GET() {
return NextResponse.json({ time: new Date().toISOString() })
}
Revalidation
export const revalidate = 60 // Revalidate every 60 seconds
export async function GET() {
const data = await fetchData()
return NextResponse.json(data)
}
CORS
export async function GET(request: NextRequest) {
const origin = request.headers.get('origin')
const response = NextResponse.json({ data: 'example' })
response.headers.set('Access-Control-Allow-Origin', origin || '*')
response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE')
response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization')
return response
}
export async function OPTIONS() {
return new NextResponse(null, {
status: 204,
headers: {
'Access-Control-Allow-Origin': '*',
'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
'Access-Control-Allow-Headers': 'Content-Type, Authorization',
},
})
}
Integration
Used by:
backend-developeragentfullstack-developeragent
Converted and distributed by TomeVault — claim your Tome and manage your conversions.