Next.js API Routes 알아보기

 

📌 API Routes 란?

API Routes 의 등장 배경

React 애플리케이션을 개발하다보면 backend API 가 필요한 시점이 오게됩니다.

예를 들어 DB 의 데이터를 조회하거나 사용자가 요청한 데이터를 처리하는 등의 작업이 있습니다.

이를 위해 이전에는 Node.js 등을 활용한 custom server 파이프라인을 구축해서

해당 작업을 위임하는 방식을 사용했지만, 이 경우 Next.js 의 성능 최적화 이점을 잃게 되는 문제와

TypeScript 및 ES6 방식의 모듈 시스템을 사용하지 못하는 문제가 있었습니다.

 

이러한 문제를 해결하며 개발자 경험을 향상시키기 위해서 Next.js 는 Next 9 버전 부터

API Routes 라는 기능을 지원하기 시작했습니다.

이를 통해 Next.js 안에서 필요한 serverless API Endpoint 를 구축할 수 있게 되었습니다.

 

API Routes 를 활용한 REST API 예시

Next.js 는 Express 와 같은 Node.js 서버사이드 프레임워크처럼

Node.js 의 요청 및 응답객체를 직접 접근하지 않고 NextApiRequest 와 같이

래핑된 객체를 손쉽게 다룰 수 있는 인터페이스를 제공합니다.

이를 통해 불필요한 파싱 코드를 줄이고 원하는 비즈니스 로직 구현에 집중할 수 있게 됩니다.

 

API Routes 는 pages/api 디렉토리 내에 정의하며 파일 시스템을 기반으로 주소가 결정됩니다.

여기서는 댓글을 조회하는 간단한 API 예시를 통해 사용 방법을 알아보겠습니다.

핸들러는 요청(req) 과 응답(res) 객체를 인자로 전달받습니다.

 

// pages/api/comments

const comments = [
    { id: 1, text: 'comment 1' },
    { id: 2, text: 'comment 2' },
    { id: 3, text: 'comment 3' }, 
]

export default function handler(req, res) {
    res.status(200).json(comments)
}

 

이제 위에서 정의한 endpoint 로 fetch 를 통해 데이터를 요청합니다.

 

// Comments.tsx

export default function Comments() {
    const fetchComments = async () => {
        const response = await fetch('/api/comments')

        if (response.ok) {
            const comments = await response.json()
        }
    }
}

 

📌 API Routes 의 적용 사례

API Proxy

API Routes 를 이용하면 실제 외부 API 호출전에 요청 및 응답 객체에 접근하여

Authorization, CORS 등 여러 목적을 위한 프록시 역할을 수행할 수 있습니다.

 

1️⃣ 유효성 검사

다음은 HTTP Request 에서 Authorization 헤더를 검사해

API 요청 조건을 만족하는지 판단하는 간단한 예시 코드입니다.

 

import { NextApiRequest, NextApiResponse } from 'next'

export async function handler(req: NextApiRequest, res: NextApiResponse) {
    const role = req.headers.get('authorization')

    if (['user', 'admin'].includes(role)) {
        return res.status(401).send('unauthorized')
    }

    // ...
}

 

2️⃣ 외부 API 주소 마스킹

또한 API Routes 를 이용해 프로젝트에서 사용하는 외부 API 를 은닉화 할 수 있습니다.

만약 실제 외부 API 주소가 https://external-api.hub/comment 라면,

/api/external 이라는 요청으로 실제 요청 주소를 숨길 수 있습니다.

 

// pages/api/external

import { NextApiRequest, NextApiResponse } from 'next'

const API_BASE_URL = process.env.API_BASE_URL

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
    // ...

    const requestUrl = `${API_BASE_URL}/${req.path}`
    const response = await fetch(requestUrl)
}

 

📌 API Routes 유의사항

Live Connection 이 필요한 경우 부적합하다

Next.js 에서 제공하는 API Routes 는 serverless function 이기 때문에

stateless 하여 지속적인 DB 커넥션을 유지하거나 web socket 등을 이용한 실시간 통신 등의

live connection 이 필요한 경우에는 적합하지 않을 수 있습니다.

 

중복된 API fetch 조심하기

API Routes 를 getServerSideProps 나 getStaticProps 등에서 사용하면

불필요하게 API 를 두번 호출하는 문제가 발생할 수 있습니다.

 

/** 
 * lib/load-posts.js
 *
 * loadPosts 는 lib/* 와 같은 디렉토리에서 공통 함수로 관리하면
 * getStaticProps와 API routes에서 모두 접근할 수 있습니다. 
 */
export async function loadPosts() {
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

/**
 * api/post
 */
import { loadPosts } from '@lib/load-posts'

export default async function handler(req, res) {
    // ...

    const posts = await loadPosts()

    res.status(200).json(posts)
}

/**
 * pages/blog.js
 */
import { loadPosts } from '@lib/load-posts'

export async function getStaticProps() {
    /**
     * API Routes 를 사용하는 대신에 API 를 직접 조회하는 함수를 호출해서
   * 불필요한 API 중복 호출을 방지합니다.
   */
  const posts = await loadPosts()

  return { props: { posts } }
}

 

📌 Edge API Routes (🧪 experimental)

Edge API Routes 는 Next v12 에서 추가된 기능으로서

기존의 Node.js 기반의 런타임보다 가볍고 빠른 환경을 제공합니다.

현재는 베타 버전으로 다음과 같이 edge runtime 을 활성화 시키고 싶은 라우트에서

runtime config 를 export 하면 설정할 수 있습니다.

 

import type { NextRequest } from 'next/server';

export default (req: NextRequest) => {
  return new Response(`Hello, from ${req.url} I'm now an Edge API Route!`);
};

export const config = {
  runtime: 'experimental-edge',
};

 

Edge API Routes 는 표준 WEB API 를 기반으로 만들어졌기 때문에 사용 시 몇가지 제약사항 이 있습니다.

대신 stream response 를 통해 보다 빠른 TTFB(Time To First Byte) 로

성능향상을 꾀할 수 있다는 장점이 있습니다.

 

📌 참고자료

Next.js 9

Advanced Features: Custom Server | Next.js

Are there any downsides or limitations of using Next.js api routes instead of custom server? · Discussion #17679 · vercel/next.js