Belajar API Route Next.js: Validasi, Rate Limit, Versioning

export async function POST(request: NextRequest) {
  const clientIp = getClientIp(request);
  const rateLimit = checkRateLimit(`contact:${clientIp}`, {
    limit: RATE_LIMIT,
    window: 60,
  });
  if (!rateLimit.success) {
    return rateLimited(RATE_LIMIT, rateLimit.resetIn);
  }

  let body: ContactBody;
  try {
    body = await request.json();
  } catch {
    return apiError({
      status: 400,
      code: "invalid_json",
      message: "Invalid JSON",
      hint: "Send a JSON object as the body, with Content-Type: application/json.",
    });
  }

Dua penjaga pertama. Limiter berjalan sebelum body dibaca, dan kuncinya adalah nama route yang digabung dengan alamat klien. Parse JSON berada di try dan catch sehingga body rusak menjadi 400 dengan code invalid_json, bukan exception yang tidak tertangani.

  const clamp = (v: unknown, max: number): string =>
    typeof v === "string" ? v.trim().slice(0, max) : "";

  const name = clamp(body.name, 100);
  const email = clamp(body.email, 200);
  const intent = body.intent === "hr" ? "hr" : "project";
  const company = clamp(body.company, 120);
  const role = clamp(body.role, 120);
  const projectType = clamp(body.projectType, 80);
  const timeline = clamp(body.timeline, 80);
  const message = clamp(body.message, 5000);

  if (name.length < 2) {
    return apiError({
      status: 400,
      code: "invalid_request",
      message: "Please provide a valid name.",
      hint: "`name` must be 2 to 100 characters.",
    });
  }
  if (!EMAIL_RE.test(email)) {
    return apiError({
      status: 400,
      code: "invalid_request",
      message: "Please provide a valid email.",
      hint: "`email` must be a valid email address of at most 200 characters.",
    });
  }

Paksa ke bentuk aman, lalu periksa. clamp mengubah apa pun yang bukan string menjadi string kosong dan memotong sisanya sampai panjang maksimum, sehingga pemeriksaan di bawahnya hanya melihat string pendek. Setiap hint menyebut field dan rentang yang diizinkan.

  try {
    const { error } = await getResend(apiKey).emails.send({
      from: fromEmail,
      to: toEmail,
      replyTo: email,
      template: {
        id: isHiring ? TEMPLATE_HIRING : TEMPLATE_PROJECT,
        variables,
      },
    });

    if (error) {
      console.error("Resend send error:", error);
      return apiError({
        status: 502,
        code: "upstream_error",
        message: "Failed to send message.",
        hint: "The email provider rejected the message. Retry later, or email matthewswong2610@gmail.com directly.",
      });
    }

    return NextResponse.json({ success: true });

Pemanggilan dari server. SDK mengembalikan error alih-alih melempar exception, jadi route memeriksanya, mencatat detail provider di server, dan menjawab 502 upstream_error dengan pesan umum. Id template dan variabel menggantikan body HTML.

export function rateLimited(limit: number, resetIn: number): Response {
  return apiError({
    status: 429,
    code: "rate_limited",
    message: "Too many requests. Please try again later.",
    hint: `Wait ${resetIn} seconds before retrying; the limit is ${limit} requests per minute per client.`,
    retryAfter: resetIn,
    headers: {
      "Retry-After": String(resetIn),
      "X-RateLimit-Limit": String(limit),
      "X-RateLimit-Remaining": "0",
      "X-RateLimit-Reset": String(resetIn),
    },
  });
}

Satu helper membangun 429. Retry-After membawa waktu tunggu dalam detik, header X-RateLimit menjelaskan jendela waktunya, dan retryAfter mengulanginya di body untuk klien yang hanya membaca JSON. Hint memberi tahu orang apa yang harus dilakukan.

// Version 1 of the contact endpoint. The handler lives at app/api/contact,
// which stays as a deprecated, unversioned alias (see next.config.ts).
export { POST, GET, PUT, PATCH, DELETE } from "@/app/api/contact/route";

// Resend needs the Node.js runtime; segment config is never re-exported.
export const runtime = "nodejs";

Seluruh endpoint v1. Ia me-re-export setiap method dari handler asli, sehingga v1 dan alias deprecated tidak mungkin berbeda. Runtime tetap dideklarasikan sendiri; komentarnya menyebut segment config tidak pernah ikut di-re-export.

export const DEPRECATED_API_ALIASES = [
  { path: "/api/chat", successor: API_PATHS.chat },
  { path: "/api/chat/followups", successor: API_PATHS.followups },
  { path: "/api/contact", successor: API_PATHS.contact },
] as const;

Path lama sebagai data. next.config.ts membaca daftar ini untuk menambahkan header Deprecation dan Link pada tiap alias, dan panduan developer serta deskripsi OpenAPI membaca daftar yang sama, sehingga path yang deprecated cukup dideklarasikan sekali.

  // Fall back to the LAST X-Forwarded-For entry, not the first. Both Cloudflare
  // and nginx's $proxy_add_x_forwarded_for append, so the leftmost entry is
  // whatever the client chose to send: reading it let anyone mint a fresh
  // rate-limit bucket per request with `X-Forwarded-For: 1.2.3.<random>`, which
  // defeated every limit here — including the Groq spend and the Resend send
  // path. The rightmost entry is the one our own proxy wrote.
  const forwarded = request.headers.get("x-forwarded-for");
  if (forwarded) {
    const hops = forwarded
      .split(",")
      .map((hop) => hop.trim())
      .filter(Boolean);
    if (hops.length > 0) {
      return hops[hops.length - 1];
    }
  }

Alamat mana yang dianggap klien? Entri forwarded paling kiri adalah apa pun yang dikirim pemanggil, jadi kode membaca yang terakhir, yang ditulis proxy milik situs. Komentarnya mencatat bug yang digantikan oleh kode ini.