API route conventions

export async function GET(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
  // 1. Auth — always first
  const session = await getSession();
  if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });

  // 2. Permission check
  if (!hasPermission(session.user.role, "module:action")) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
  }

  // 3. Ownership / IDOR check
  const resource = await db.resource.findUnique({ where: { id: (await params).id } });
  if (!resource) return NextResponse.json({ error: "Not found" }, { status: 404 });
  if (resource.tenantId !== session.user.tenantId) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
  }

  // 4. Input validation with Zod (POST/PATCH)
  const parsed = schema.safeParse(body);
  if (!parsed.success) {
    return NextResponse.json(
      { error: "Validation failed", details: parsed.error.flatten() },
      { status: 400 }
    );
  }

  // 5. Business logic in the service layer — never inline
  const result = await myService.doThing(parsed.data);

  // 6. Audit log every state-changing operation
  await logAudit({ action: "RESOURCE_UPDATED", entityId: resource.id, userId: session.user.id });

  // 7. Standardised response
  return NextResponse.json({ success: true, data: result });
}

// WRONG — silently swallows the failure
try {
  await risky();
} catch {}

// CORRECT — log, then handle
try {
  await risky();
} catch (error) {
  logger.error("risky failed", { error });
  return NextResponse.json({ success: false, error: "…" }, { status: 500 });
}