App Router에서 API Route 다루기 (Route Handlers)

next js 를 사용하면서 가장 강력한 장점 중에 하나인 API route에 대해 써본 기억이 잘 없었습니다. 이번에 맡을 업무에서 사용할 일이 생길 것 같아 간단히 정리해보고자 합니다.

✅ App Router에서 API는 어떻게 만들까?

App Router 구조에서는 app/api/ 폴더 안에 라우트를 만들고, 그 안에 route.ts(또는 route.js) 파일을 만들어서 API를 구성합니다.

📁 디렉토리 구조 예시

app/
  api/
    hello/
      route.ts

이렇게 만들면 /api/hello 경로에 대한 API가 생성됩니다.

✅ 기본 사용법

---

// app/api/hello/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
  return NextResponse.json({ message: '안녕하세요, App Router!' });
}
export async function POST(request: Request) {
  const body = await request.json();
  return NextResponse.json({ received: body });
}

---

//→ 클라이언트에서 다음과 같이 요청
const res = await fetch('/api/hello');
const data = await res.json();

---

✅ 장점 (App Router API Routes)

• Web API 표준에 맞춘 Request/Response 객체 사용
• 파일 기반 라우팅을 API에도 적용
• 클라이언트 컴포넌트와 서버 로직을 더 명확하게 분리
• Middleware, 서버 컴포넌트와의 연계가 쉬움
• 향후 Next.js의 핵심 API 방식으로 유지될 가능성 높음

✅ 실전 예제: reCAPTCHA v2 검증 API 만들기

이번에 Google reCAPTCHA v2(“나는 로봇이 아닙니다” 체크박스)를 사용할 일이 생기면서, 클라이언트에서 받은 인증 토큰을 서버에서 검증하는 API를 만들게 되었습니다. App Router 기반의 API Routes를 활용하여 구현할 예정이라 미리 예상을 하고 틀을 짜보았습니다!

📁 디렉토리 구조 예시
app/
  api/
    verify-recaptcha/
      route.ts

//🧩 서버 API 코드 (app/api/verify-recaptcha/route.ts)
import { NextResponse } from 'next/server';
export async function POST(request: Request) {
  const { token } = await request.json();
  const secret = process.env.RECAPTCHA_SECRET_KEY;
  const response = await fetch('구글 reCAPTCHA 검증 API 엔드포인트', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: `secret=${secret}&response=${token}`,
  });
  const data = await response.json();
  if (data.success) {
    return NextResponse.json({ verified: true });
  } else {
    return NextResponse.json({ verified: false }, { status: 400 });
  }
}

//🧩 클라이언트 코드 예시 (React + react-google-recaptcha 사용)
'use client';
...
export default function RecaptchaForm() {
... 기타 로직 ~
    const res = await fetch('/api/verify-recaptcha', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ token }),
    });
    const data = await res.json();
    setVerified(data.verified);
  };
  return (
    <div>
      <ReCAPTCHA
        sitekey={process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY!}
        ref={recaptchaRef}
      />
     ...
    </div>
  );
}

API Route는 단순한 테스트용 API뿐 아니라, 이런 식으로 클라이언트 보안 처리나 외부 API 연동에도 매우 유용하게 활용할 수 있습니다.
reCAPTCHA 같이 민감한 인증 로직은 절대 클라이언트에서 처리해서는 안 되며, 항상 서버에서 검증하는 것이 보안상 안전합니다.
App Router에서 제공하는 API Routes 기능은 이러한 서버 역할을 깔끔하게 수행할 수 있도록 도와줍니다.