nextjs-api-routes

Next.js API Routes - Pattern Library

Purpose

Comprehensive guide for building API routes in Next.js 15 for the AIProDaily platform, including request handling, error management, authentication, and performance optimization.

When to Use

Automatically activates when:

Creating new API routes in app/api/**/*.ts
Working with NextRequest/NextResponse
Configuring route timeouts
Handling authentication
Processing API requests
Building server-side endpoints

Quick Start: API Route Template

Standard POST Route

// app/api/[feature]/route.ts import { NextRequest, NextResponse } from 'next/server' import { supabaseAdmin } from '@/lib/supabase'

export async function POST(request: NextRequest) { try { // 1. Parse request body const body = await request.json()

// 2. Validate required fields
if (!body.campaignId) {
  return NextResponse.json(
    { error: 'Missing required field: campaignId' },
    { status: 400 }
  )
}

// 3. Extract newsletter context (from body or auth)
const newsletterId = body.newsletter_id

// 4. Perform operation
const result = await processData(body, newsletterId)

// 5. Return success response
return NextResponse.json({
  success: true,
  data: result
})

} catch (error: any) { // 6. Handle errors console.error('[API] Error in /api/feature:', error.message) return NextResponse.json( { error: error.message || 'Internal server error' }, { status: 500 } ) } }

// 7. Configure timeout for long-running operations export const maxDuration = 600 // 10 minutes

Route Configuration

maxDuration Settings

Default: 10 seconds Maximum:

Pro plan: 300 seconds (5 minutes) for serverless
Pro plan: 900 seconds (15 minutes) for Edge Runtime
Workflow steps: 800 seconds (13 minutes)

// Short operations (default) export const maxDuration = 10 // 10 seconds

// Medium operations (API calls, database queries) export const maxDuration = 60 // 1 minute

// Long operations (RSS processing, content generation) export const maxDuration = 300 // 5 minutes

// Very long operations (campaign workflow, batch processing) export const maxDuration = 600 // 10 minutes

// Workflow steps only export const maxDuration = 800 // 13 minutes (workflow routes only)

Runtime Configuration

// Use Edge Runtime for faster cold starts (limited Node.js APIs) export const runtime = 'edge'

// Use Node.js runtime for full compatibility (default) export const runtime = 'nodejs'

// Dynamic route (disable static optimization) export const dynamic = 'force-dynamic'

HTTP Methods

GET Route

export async function GET(request: NextRequest) { try { // Extract query parameters const searchParams = request.nextUrl.searchParams const campaignId = searchParams.get('campaignId') const newsletterId = searchParams.get('newsletter_id')

if (!newsletterId) {
  return NextResponse.json(
    { error: 'newsletter_id required' },
    { status: 400 }
  )
}

// Fetch data
const { data, error } = await supabaseAdmin
  .from('newsletter_campaigns')
  .select('id, status, date')
  .eq('newsletter_id', newsletterId)
  .eq('id', campaignId)
  .single()

if (error) {
  throw new Error(error.message)
}

return NextResponse.json({ data })

} catch (error: any) { console.error('[API GET] Error:', error.message) return NextResponse.json( { error: error.message }, { status: 500 } ) } }

export const maxDuration = 30

POST Route (with validation)

export async function POST(request: NextRequest) { try { const body = await request.json()

// Validate input
const validation = validateInput(body)
if (!validation.valid) {
  return NextResponse.json(
    { error: validation.error },
    { status: 400 }
  )
}

// Process request
const result = await processRequest(body)

return NextResponse.json({
  success: true,
  data: result
})

} catch (error: any) { console.error('[API POST] Error:', error.message) return NextResponse.json( { error: error.message }, { status: 500 } ) } }

function validateInput(body: any): { valid: boolean; error?: string } { if (!body.newsletter_id) { return { valid: false, error: 'newsletter_id is required' } } if (!body.campaignId) { return { valid: false, error: 'campaignId is required' } } return { valid: true } }

export const maxDuration = 120

PUT Route (update)

export async function PUT(request: NextRequest) { try { const body = await request.json() const { id, newsletter_id, ...updates } = body

if (!id || !newsletter_id) {
  return NextResponse.json(
    { error: 'id and newsletter_id required' },
    { status: 400 }
  )
}

const { data, error } = await supabaseAdmin
  .from('articles')
  .update(updates)
  .eq('id', id)
  .eq('newsletter_id', newsletter_id)
  .select()
  .single()

if (error) {
  throw new Error(error.message)
}

return NextResponse.json({ data })

} catch (error: any) { console.error('[API PUT] Error:', error.message) return NextResponse.json( { error: error.message }, { status: 500 } ) } }

export const maxDuration = 30

DELETE Route

export async function DELETE(request: NextRequest) { try { const searchParams = request.nextUrl.searchParams const id = searchParams.get('id') const newsletterId = searchParams.get('newsletter_id')

if (!id || !newsletterId) {
  return NextResponse.json(
    { error: 'id and newsletter_id required' },
    { status: 400 }
  )
}

const { error } = await supabaseAdmin
  .from('articles')
  .delete()
  .eq('id', id)
  .eq('newsletter_id', newsletterId)

if (error) {
  throw new Error(error.message)
}

return NextResponse.json({ success: true })

} catch (error: any) { console.error('[API DELETE] Error:', error.message) return NextResponse.json( { error: error.message }, { status: 500 } ) } }

export const maxDuration = 30

Dynamic Routes

Route with Parameters

// app/api/campaigns/[id]/route.ts export async function GET( request: NextRequest, { params }: { params: { id: string } } ) { try { const campaignId = params.id const searchParams = request.nextUrl.searchParams const newsletterId = searchParams.get('newsletter_id')

if (!newsletterId) {
  return NextResponse.json(
    { error: 'newsletter_id required' },
    { status: 400 }
  )
}

const { data, error } = await supabaseAdmin
  .from('newsletter_campaigns')
  .select('*')
  .eq('id', campaignId)
  .eq('newsletter_id', newsletterId)
  .single()

if (error) {
  throw new Error(error.message)
}

return NextResponse.json({ data })

} catch (error: any) { console.error('[API] Error:', error.message) return NextResponse.json( { error: error.message }, { status: 500 } ) } }

Authentication Patterns

Protected Route (Server-Side)

import { cookies } from 'next/headers' import { createServerClient } from '@supabase/ssr'

export async function GET(request: NextRequest) { try { // Create Supabase client with cookies const cookieStore = cookies() const supabase = createServerClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, { cookies: { get(name: string) { return cookieStore.get(name)?.value }, }, } )

// Check authentication
const { data: { user }, error: authError } = await supabase.auth.getUser()

if (authError || !user) {
  return NextResponse.json(
    { error: 'Unauthorized' },
    { status: 401 }
  )
}

// Process authenticated request
const result = await processAuthenticatedRequest(user)

return NextResponse.json({ data: result })

} catch (error: any) { console.error('[API] Error:', error.message) return NextResponse.json( { error: error.message }, { status: 500 } ) } }

CRON Secret Validation

export async function GET(request: NextRequest) { try { // Validate CRON secret const authHeader = request.headers.get('authorization') const cronSecret = process.env.CRON_SECRET

if (!cronSecret || authHeader !== `Bearer ${cronSecret}`) {
  return NextResponse.json(
    { error: 'Unauthorized' },
    { status: 401 }
  )
}

// Process cron job
const result = await processCronJob()

return NextResponse.json({
  success: true,
  data: result
})

} catch (error: any) { console.error('[CRON] Error:', error.message) return NextResponse.json( { error: error.message }, { status: 500 } ) } }

export const maxDuration = 300

Error Handling Patterns

Standard Error Handler

function handleApiError(error: any, context: string) { console.error([API Error - ${context}], { message: error.message, stack: error.stack, timestamp: new Date().toISOString() })

// Return user-friendly error return NextResponse.json( { error: error.message || 'An unexpected error occurred', context: context }, { status: error.status || 500 } ) }

// Usage export async function POST(request: NextRequest) { try { const body = await request.json() const result = await processData(body) return NextResponse.json({ data: result }) } catch (error: any) { return handleApiError(error, 'POST /api/feature') } }

Validation Error Pattern

class ValidationError extends Error { status = 400

constructor(message: string) { super(message) this.name = 'ValidationError' } }

function validateRequest(body: any) { if (!body.newsletter_id) { throw new ValidationError('newsletter_id is required') } if (!body.campaignId) { throw new ValidationError('campaignId is required') } // More validations... }

export async function POST(request: NextRequest) { try { const body = await request.json() validateRequest(body) const result = await processData(body) return NextResponse.json({ data: result }) } catch (error: any) { const status = error.status || 500 return NextResponse.json( { error: error.message }, { status } ) } }

Response Patterns

Success Response

return NextResponse.json({ success: true, data: result, timestamp: new Date().toISOString() })

Error Response

return NextResponse.json( { error: 'Descriptive error message', code: 'ERROR_CODE', details: additionalInfo }, { status: 400 } )

Paginated Response

return NextResponse.json({ data: items, pagination: { page: currentPage, limit: pageSize, total: totalItems, hasMore: hasNextPage } })

Headers and CORS

Set Custom Headers

export async function GET(request: NextRequest) { const data = await fetchData()

return NextResponse.json({ data }, { headers: { 'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=30', 'X-Custom-Header': 'value' } }) }

CORS Configuration

export async function OPTIONS(request: NextRequest) { return new NextResponse(null, { status: 200, headers: { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization', }, }) }

export async function POST(request: NextRequest) { const response = NextResponse.json({ data: result }) response.headers.set('Access-Control-Allow-Origin', '*') return response }

Best Practices

✅ DO:

Always validate input parameters
Use appropriate maxDuration for operation length
Filter by newsletter_id for tenant-scoped data
Return consistent response formats
Log errors with context
Use try-catch for error handling
Set appropriate HTTP status codes
Validate authentication when needed

❌ DON'T:

Expose sensitive error details to clients
Skip input validation
Use default 10s timeout for long operations
Return raw database errors
Forget to check newsletter_id
Skip error logging
Use inconsistent response formats

Common Patterns

Batch Processing

export async function POST(request: NextRequest) { try { const { items, newsletter_id } = await request.json()

const results = await Promise.all(
  items.map(item => processItem(item, newsletter_id))
)

return NextResponse.json({
  success: true,
  processed: results.length,
  results
})

} catch (error: any) { console.error('[API Batch] Error:', error.message) return NextResponse.json( { error: error.message }, { status: 500 } ) } }

export const maxDuration = 300

Streaming Response (for long operations)

export async function GET(request: NextRequest) { const stream = new ReadableStream({ async start(controller) { try { const items = await fetchLargeDataset()

    for (const item of items) {
      const chunk = JSON.stringify(item) + '\n'
      controller.enqueue(new TextEncoder().encode(chunk))
    }

    controller.close()
  } catch (error) {
    controller.error(error)
  }
}

})

return new NextResponse(stream, { headers: { 'Content-Type': 'application/x-ndjson', 'Transfer-Encoding': 'chunked' } }) }

export const maxDuration = 600

Skill Status: ACTIVE ✅ Line Count: < 500 ✅ Framework: Next.js 15 App Router ✅

nextjs-api-routes

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

ai-content-generation

supabase-database-ops

newsletter-campaign-workflow

skill-developer