Next.js API 라우트 실습 가이드

학습 목표

Next.js에서는 pages/api 디렉토리 하위에 파일을 생성하면 API 엔드포인트를 만들 수 있습니다.

이 기능을 통해 별도의 백엔드 없이도 데이터를 받아 처리할 수 있으며, 간단한 서버 역할을 수행할 수 있습니다.

1. 기본 API 라우트 만들기 (GET 방식)

1-1. 파일 생성

pages/api/hello.js

1-2. 코드 작성

export default function handler(req, res) {
  res.status(200).json({ message: 'Hello from Next.js API!' });
}

1-3. 테스트

브라우저에서 아래 주소로 접속

http://localhost:3000/api/hello

응답 결과:

{ "message": "Hello from Next.js API!" }

2. 클라이언트에서 API 호출하기

// pages/client-test.js
import { useEffect, useState } from 'react';

export default function ClientTest() {
  const [message, setMessage] = useState('');

  useEffect(() => {
    fetch('/api/hello')
      .then((res) => res.json())
      .then((data) => setMessage(data.message));
  }, []);

  return <h1>{message}</h1>;
}

브라우저에서 /client-test 접속 시, API의 메시지가 출력됩니다.

3. POST 요청 처리 실습: Echo API 만들기

3-1. API 라우트 생성

pages/api/echo.js

3-2. 코드 작성

export default function handler(req, res) {
  if (req.method === 'POST') {
    const { text } = req.body;
    res.status(200).json({ received: text });
  } else {
    res.status(405).json({ error: 'Method Not Allowed' });
  }
}

3-3. 클라이언트 페이지 작성

// pages/client-post.js
import { useState } from "react";

export default function ClientPost() {
  const [input, setInput] = useState('');
  const [response, setResponse] = useState('');

  const handleSubmit = async (e) => {
    e.preventDefault();

    const res = await fetch('/api/echo', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ text: input }),
    });

    const data = await res.json();
    setResponse(data.received);
  };

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <input 
          type="text" 
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="메시지 입력"
        />
        <button type="submit">보내기</button>
      </form>
      {response && <p>응답 : {response}</p>}
    </div>
  );
}

3-4. 동작 흐름 요약

• 입력창에 텍스트 작성 후 보내기 클릭
• /api/echo로 POST 요청 전송
• API는 req.body.text 값을 받아 { received: text } 형식으로 응답
• 클라이언트는 응답을 받아 화면에 출력

4. 마무리 및 다음 단계 예고

이번 실습을 통해 GET 및 POST 방식의 API 라우트를 구현하고 클라이언트와 데이터를 주고받는 기본 흐름을 이해했습니다.

다음 단계에서는 입력값을 저장하거나, 목록을 관리하는 등 더 발전된 API 응용 방법을 다룰 예정입니다.