API Routes

Docs

• Next.js - API Routes

API Routes는 Next.js에서 API를 구축할 수 있게 해주는 기능이다.
프론트엔드 프로젝트 안에서 백엔드 API 엔드포인트를 함께 정의할 수 있다.

즉, 클라이언트 → API 요청 → 서버 로직 실행 → 응답 반환
이 흐름을 Next.js 하나로 처리할 수 있다.

일반적인 백엔드 API 서버처럼, 브라우저로부터 요청을 받아 서버에서 실행되는 로직을 정의할 수 있으며, 데이터베이스 조회나 외부(서드파티) API 호출 후 가공된 결과를 응답으로 반환할 수 있다.

🤔 API Routes가 필요한 이유

프론트엔드 개발을 하다 보면, 브라우저에서 직접 처리하면 위험하거나 숨겨야 하는 작업들이 생긴다.
예를 들어 API Key, 인증 처리, 데이터 검증, DB 접근 등이 있다.

API Routes는 이런 작업들을 서버에서 안전하게 처리할 수 있도록 Next.js에서 제공하는 서버 레이어다.

API Routes의 동작 구조

1. 브라우저에서 /api/...로 요청
2. Next.js 서버가 해당 API 파일을 서버에서 실행
3. JSON 등의 응답을 클라이언트에 반환

API Routes의 코드는 절대 브라우저에서 실행되지 않는다.

Page Router에서의 API Routes

📁 pages/
└── 📁 api/
    └── hello.ts

pages 폴더 아래에 api 폴더를 만들고,
그 안에 파일을 생성하면 해당 파일은 페이지가 아닌 API Route로 동작한다.
파일 경로는 그대로 API 엔드포인트가 된다.

• pages/api/hello.ts → /api/hello

pages/api/hello.ts

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import type { NextApiRequest, NextApiResponse } from 'next';

type Data = {
  name: string;
};

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>,
) {
  res.status(200).json({ name: 'John Doe' });
}

• req : 요청 정보 (method, query, body 등)
• res : 응답 제어 (status, json, end 등)

handler 함수는 요청 req과 응답 res객체를 매개변수로 받는다.
함수 내부에서는res.json()을 통해 응답 데이터를 반환하고,
res.status()를 사용해 HTTP 상태 코드를 설정할 수 있다.

위 예제에서는 요청이 정상적으로 처리되었음을 의미하는 200 상태 코드와 함께
{ name: 'John Doe' } 데이터를 JSON 형태로 응답한다.

HTTP Method 분기

export default function handler(req, res) {
  if (req.method === 'GET') {
    return res.status(200).json({ data: [] });
  }

  if (req.method === 'POST') {
    return res.status(201).json({ success: true });
  }

  res.status(405).end(); // Method Not Allowed
}

Page Router에서는 req.method를 기준으로 HTTP Method를 분기 처리할 수 있다.
REST API 패턴을 그대로 적용할 수 있다.

App Router에서의 API Routes

App Router에서는 API Routes를 Route Handler라고 부르며, route.ts 파일을 사용한다.

📁 app/
└── 📁 api/
    └── 📁 posts/
        └── route.ts

app/api/posts/route.ts

import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ posts: [] });
}

export async function POST(req: Request) {
  const body = await req.json();
  return NextResponse.json({ success: true });
}

App Router의 특징은 다음과 같다.

• HTTP Method를 함수 단위로 명시
• Web Standard 기반 (Request, Response)
• Edge Runtime 사용 가능

Page Router vs App Router API Routes 차이

구분	Page Router	App Router
위치	pages/api	app/api
파일	단일 handler	route.ts
Method 처리	req.method	GET, POST 함수
표준	Node 중심	Web 표준
Edge 지원	X	O

언제 API Routes를 쓰면 좋을까?

• 프론트엔드 프로젝트에서 서버 로직이 필요할 때
• 간단한 CRUD / 인증 처리
• 외부 API 프록시
• 개인 프로젝트 / MVP
• 프론트엔드 개발자가 서버 흐름까지 이해하고 싶을 때

대규모 트래픽이나 복잡한 도메인 로직이 필요한 경우에는 별도의 백엔드 서버를 두는 것이 더 적합하다.