Next.js API Routes 완벽 정리

1. Next.js API Routes란?

✅ Next.js에서 제공하는 서버리스 API 엔드포인트
✅ pages/api/ 디렉토리에 있는 파일이 자동으로 API 라우트가 됨
✅ 서버리스 환경에서 실행되므로 별도의 Express 서버 없이 API 제공 가능
✅ TypeScript 지원 (NextApiRequest, NextApiResponse)
✅ JSON 데이터 응답을 쉽게 반환 가능

💡 API Routes를 사용하면

• 클라이언트에서 데이터를 요청하여 가져올 수 있음 (fetch, axios 활용)
• 데이터를 백엔드 API로 가공하여 프론트엔드에서 활용 가능
• Next.js에서 SSR(Server Side Rendering) 및 SSG(Static Site Generation) 시 API 데이터를 직접 활용 가능

---

2. 기본 API 라우트 생성하기

📌 pages/api/hello.ts

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" });
}

🔹 동작 방식

1. 파일 위치: pages/api/hello.ts
2. API 엔드포인트: http://localhost:3000/api/hello
3. API 응답(JSON)

   {
     "name": "John Doe"
   }
   

4. NextApiRequest, NextApiResponse 타입 적용
   • req: HTTP 요청 객체 (클라이언트에서 전달한 데이터 접근 가능)
   • res: HTTP 응답 객체 (클라이언트에게 JSON 데이터 반환)

---

3. 현재 시간을 반환하는 API 만들기

📌 pages/api/time.ts

import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const date = new Date();
  res.json({ time: date.toLocaleString() });
}

🔹 동작 방식

1. 파일 위치: pages/api/time.ts
2. API 엔드포인트: http://localhost:3000/api/time
3. API 응답(JSON)

   {
     "time": "2025-02-23 14:30:00"
   }
   

4. 동작 원리
   • new Date()를 사용하여 현재 시간 생성
   • date.toLocaleString()을 이용해 문자열로 변환하여 응답

💡 이 API는 클라이언트가 요청할 때마다 현재 시간을 반환하므로, 실시간 데이터를 제공할 수 있음.

---

4. GET, POST 요청 구분하기

Next.js API에서는 **req.method**를 사용하여 GET, POST 등 HTTP 메서드를 구분할 수 있습니다.

📌 pages/api/method.ts

import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method === "GET") {
    res.status(200).json({ message: "GET 요청입니다." });
  } else if (req.method === "POST") {
    res.status(200).json({ message: "POST 요청입니다." });
  } else {
    res.status(405).json({ message: "허용되지 않은 메서드입니다." });
  }
}

✅ 동작 방식

요청 방식 응답

GET /api/method	{ "message": "GET 요청입니다." }
POST /api/method	{ "message": "POST 요청입니다." }
PUT /api/method	{ "message": "허용되지 않은 메서드입니다." } (405 오류)

💡 API에서 특정 HTTP 메서드만 처리하도록 설정 가능
(예: GET 요청만 받도록 제한하거나, POST 요청만 처리)

---

5. 쿼리 스트링(Query String) 처리

API 요청 시 쿼리 스트링(예: ?name=Alice)을 받아서 처리할 수도 있습니다.

📌 pages/api/greet.ts

import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { name } = req.query; // 쿼리 파라미터에서 name 추출
  res.status(200).json({ greeting: `Hello, ${name || "Guest"}!` });
}

✅ 동작 방식

요청 URL 응답

/api/greet?name=Alice	{ "greeting": "Hello, Alice!" }
/api/greet	{ "greeting": "Hello, Guest!" }

💡 req.query를 사용하면 클라이언트가 보낸 URL의 쿼리 스트링을 쉽게 추출할 수 있습니다.

---

6. POST 요청에서 JSON 데이터 받기

클라이언트가 POST 요청을 통해 데이터를 전송하면, req.body에서 값을 읽을 수 있습니다.

📌 pages/api/user.ts

import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method === "POST") {
    const { name, age } = req.body; // 요청 바디에서 데이터 추출
    res.status(200).json({ message: `이름: ${name}, 나이: ${age}` });
  } else {
    res.status(405).json({ message: "허용되지 않은 메서드입니다." });
  }
}

✅ 요청 예제 (fetch 사용)

fetch("/api/user", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Alice", age: 25 })
})
.then(res => res.json())
.then(data => console.log(data));

✅ 동작 방식

요청 방식 요청 데이터 응답

POST /api/user	{ "name": "Alice", "age": 25 }	{ "message": "이름: Alice, 나이: 25" }
GET /api/user	없음	{ "message": "허용되지 않은 메서드입니다." } (405 오류)

💡 req.body를 활용하면 클라이언트에서 보낸 JSON 데이터를 받아서 처리 가능

---

7. API Route에서 상태 코드 반환

API 응답 시 적절한 HTTP 상태 코드를 반환하는 것이 중요합니다.

📌 res.status(code).json(data)

res.status(200).json({ message: "성공" }); // 200 OK
res.status(400).json({ error: "잘못된 요청" }); // 400 Bad Request
res.status(401).json({ error: "권한 없음" }); // 401 Unauthorized
res.status(404).json({ error: "찾을 수 없음" }); // 404 Not Found
res.status(500).json({ error: "서버 오류" }); // 500 Internal Server Error

---

8. 결론

기능 사용 방법

기본 API 만들기	pages/api/hello.ts에서 handler 함수 작성
GET, POST 요청 구분	req.method 사용 (if (req.method === "POST"))
쿼리 스트링 처리	req.query 사용 (req.query.name)
POST 요청 데이터 처리	req.body 사용 (const { name } = req.body)
HTTP 상태 코드 반환	res.status(200).json({...})

Next.js API Routes를 활용하면 별도의 백엔드 서버 없이 강력한 API를 구현할 수 있습니다! 🚀