Route Handlers

// app/api/problems/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function GET(req: NextRequest) {
  const topic = req.nextUrl.searchParams.get('topic')
  const problems = await db.problem.findMany({ where: { topic } })
  return NextResponse.json({ items: problems })
}

export async function POST(req: NextRequest) {
  const body = await req.json()
  const parsed = CreateSchema.safeParse(body)
  if (!parsed.success) {
    return NextResponse.json(
      { error: { code: 'validation_failed', fields: parsed.error.flatten().fieldErrors } },
      { status: 422 },
    )
  }
  const created = await db.problem.create({ data: parsed.data })
  return NextResponse.json(created, { status: 201 })
}

// app/api/problems/[slug]/route.ts
export async function GET(req: NextRequest, { params }) {
  const { slug } = await params                 // a Promise in Next 15
  const problem = await getProblem(slug)
  if (!problem) return new NextResponse('Not found', { status: 404 })
  return NextResponse.json(problem)
}

// Any method not exported returns 405 automatically.
// A folder cannot have both page.tsx and route.ts — one URL, one
// handler.

// 1. Webhooks — a payment provider posting to you
// app/api/webhooks/razorpay/route.ts
export async function POST(req: NextRequest) {
  const raw = await req.text()                    // RAW body for the signature
  const signature = req.headers.get('x-razorpay-signature')
  if (!verify(raw, signature, process.env.RAZORPAY_WEBHOOK_SECRET))
    return new NextResponse('Invalid signature', { status: 401 })

  await enqueue(JSON.parse(raw))                  // process async
  return NextResponse.json({ received: true })    // answer fast
}
// Verify before parsing, respond quickly, and expect duplicates —
// handling must be idempotent.

// 2. A public API — mobile apps, partners, anything not your browser

// 3. Non-JSON responses — a CSV export, a PDF, an image, a feed
export async function GET() {
  return new NextResponse(csv, {
    headers: {
      'Content-Type': 'text/csv',
      'Content-Disposition': 'attachment; filename="report.csv"',
    },
  })
}

// 4. Streaming a response — proxying an LLM's token stream
// 5. OAuth callbacks, and anything that must set cookies precisely
// 6. Cron targets, health checks, sitemaps built on the fly

// NOT a reason: fetching data for your own server component. Call the
// database or the service directly — an internal fetch to your own
// route is a wasted HTTP round trip.

// Next 14: GET handlers are cached by default — a real surprise when
// the data is live. Next 15: not cached.
export const dynamic = 'force-dynamic'            // always fresh
export const revalidate = 60                      // or cache for a minute
// Be explicit either way, so an upgrade does not change behaviour.

// Every handler is public. Authenticate inside it, exactly as an
// action must:
const user = await getCurrentUser()
if (!user) return new NextResponse('Unauthorized', { status: 401 })

// Cron and internal endpoints need a shared secret:
if (req.headers.get('authorization') !== `Bearer ${process.env.CRON_SECRET}`)
  return new NextResponse('Unauthorized', { status: 401 })

// Rate limit anything unauthenticated — a public POST with no limit
// is an invitation:
const { success } = await ratelimit.limit(ip)
if (!success) return new NextResponse('Too many requests', { status: 429 })

// CORS only matters if another origin calls it; your own frontend is
// same-origin and needs none:
return NextResponse.json(data, {
  headers: { 'Access-Control-Allow-Origin': 'https://partner.example.com' },
})
// and export OPTIONS to answer the preflight.