[공식문서] NextJS - API Routes

Next.js는 Node.js 서버리스 함수로 API 엔드포인트를 쉽게 생성할 수 있는 API 라우트를 지원합니다. 이 레슨에서는 블로그 앱에는 필수가 아니지만 API 라우트를 사용하는 방법에 대해 간략히 설명하겠습니다.

 

이 레슨에서 다음 내용을 배울 수 있습니다:

• API 라우트를 생성하는 방법.
• API 라우트에 관한 유용한 정보.

 

시작 코드 다운로드 (선택 사항)

이전 레슨에서 진행하지 않으신다면, 이 레슨을 위한 시작 코드를 다운로드하고 설치한 후 실행할 수 있습니다. 아래 명령을 사용하여 이전 레슨의 결과와 동일한 nextjs-blog 디렉토리를 설정합니다.

 

이전 레슨을 완료한 경우 이 작업이 필요하지 않습니다.

npx create-next-app@latest nextjs-blog --use-npm --example "https://github.com/vercel/next-learn/tree/main/basics/api-routes-starter"

 

그런 다음 명령 출력에서 지시 사항을 따르세요 (디렉토리로 이동하고 개발 서버를 시작하세요).

 

또한 다음 파일을 업데이트해야 합니다.

 

• public/images/profile.jpg: 권장 사항으로, 자신의 사진으로 업데이트하세요 (권장 크기: 400px 너비/높이).
• components/layout.js 파일의 const name = '[Your Name]': 여기에 자신의 이름을 입력하세요.
• pages/index.js 파일의 <p>[Your Self Introduction]</p>: 자기 소개를 넣으세요.

 

Creating API Routes

API Routes를 사용하면 Next.js 앱 내에서 API 엔드포인트를 생성할 수 있습니다. 이를 위해 pages/api 디렉토리에 다음 형식의 함수를 생성하면 됩니다:

// req = HTTP incoming message, res = HTTP server response
export default function handler(req, res) {
  // ...
}

위의 요청 핸들러에 대한 자세한 내용은 API Routes 문서에서 확인할 수 있습니다.

 

이러한 API Routes는 Serverless Functions (또는 Lambdas로도 알려집니다)로 배포할 수 있습니다.

 

간단한 API 엔드포인트 생성

실습해 봅시다. pages/api 디렉토리에 hello.js라는 파일을 만들고 다음 코드를 추가하세요:

export default function handler(req, res) {
  res.status(200).json({ text: 'Hello' });
}

이제 http://localhost:3000/api/hello에 접속해 보세요. {"text":"Hello"}가 표시되어야 합니다. 참고로:

• req는 http.IncomingMessage의 인스턴스이며 몇 가지 미리 빌드된 미들웨어가 포함됩니다.
• res는 http.ServerResponse의 인스턴스이며 몇 가지 도움말 함수가 포함됩니다.

 

여기까지입니다! 이 레슨을 마무리하기 전에 API Routes 사용에 관한 몇 가지 유용한 팁을 다음 페이지에서 알아보겠습니다.

 

API Routes 상세 정보

다음은 API Routes에 대해 알아야 할 중요한 정보입니다.

 

getStaticProps 또는 getStaticPaths에서 API Route를 가져오지 마세요

getStaticProps 또는 getStaticPaths에서 API Route를 가져오지 마세요. 대신 직접 getStaticProps 또는 getStaticPaths에서 서버 측 코드를 작성하거나 (또는 도우미 함수를 호출하세요).

 

이렇게 하는 이유는 getStaticProps와 getStaticPaths는 서버 측에서만 실행되며 클라이언트 측에서는 실행되지 않는다는 점입니다. 더구나 이러한 함수들은 브라우저용 JS 번들에 포함되지 않습니다. 즉, 브라우저로 전송되지 않고 직접 데이터베이스 쿼리와 같은 코드를 작성할 수 있다는 것을 의미합니다. 더 자세한 내용은 서버 측 코드 작성 문서를 참조하세요.

 

좋은 사용 사례: 폼 입력 처리

API Routes를 사용하는 좋은 예는 폼 입력 처리입니다. 예를 들어 페이지에 폼을 만들고 이 폼을 API Route로 POST 요청을 보내도록 할 수 있습니다. 그런 다음 API Route에서 데이터베이스에 직접 저장하는 코드를 작성할 수 있습니다. API Route 코드는 클라이언트 번들의 일부가 아니므로 안전하게 서버 측 코드를 작성할 수 있습니다.

export default function handler(req, res) {
  const email = req.body.email;
  // Then save email to your database, etc...
}

 

미리보기 모드

Static Generation은 페이지가 headless CMS에서 데이터를 가져올 때 유용합니다. 그러나 headless CMS에서 드래프트를 작성하고 해당 드래프트를 즉시 페이지에서 미리보고 싶을 때에는 이상적이지 않습니다. 이 경우 Next.js에게 빌드 시간이 아니라 요청 시간에 이러한 페이지를 렌더링하고 게시된 내용 대신 드래프트 내용을 가져오도록 하고 싶습니다. Next.js에게는 이 특정 경우에만 Static Generation을 바이패스하도록 하고 싶습니다.

 

Next.js에는 위 문제를 해결하기 위한 미리보기 모드(Preview Mode)라는 기능이 있으며, 이 기능은 API Routes를 활용합니다. 자세한 내용은 미리보기 모드 문서를 참조하세요.

 

동적 API Routes

API Routes도 정적 페이지와 마찬가지로 동적일 수 있습니다. 자세한 내용은 동적 API Routes 문서를 참조하세요.

 

여기까지입니다!

다음으로 넘어가서 Next.js 앱을 프로덕션에 배포하는 방법에 대해 알아보겠습니다.