Next.js | API Routes

1.  API Routes 란?

- API Routes는 서버리스 함수를 생성할 수 있는 기능을 제공한다.

별도의 서버가 없이 간단히 API를 정의하고 데이터를 처리하거나 외부 API와 통신할 수 있다.

- API Routes는 Node.js 환경에서 실행되므로, Node.js의 모듈과 라이브러리를 사용할 수 있다.

- pages router에서는 pages/api 디렉토리에 파일을 생성하면 해당 파일이 API 앤드포인트로 자동 설정되고,

app router에서는 app/api/{path}/route.ts(or js) 파일을 생겅하면 해당 파일이 API 앤드포인트로 자동 설정된다.

 

참고: https://wolhyong.tistory.com/entry/Nextjs14-%EA%B0%95%EC%9D%98-13%EA%B0%95-API-Routes-%EC%82%AC%EC%9A%A9%EB%B2%95-API-%EA%B2%BD%EB%A1%9C-%EC%83%9D%EC%84%B1-%EB%B0%8F-%EB%8D%B0%EC%9D%B4%ED%84%B0-%EC%B2%98%EB%A6%AC

 

2. HTTP 메서드별 사용 방법

• App router 방식

아래와 같은 방식으로 생성하면 된다.

// app/api/geocode/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {}
export async function POST(request: Request) {}
export async function PUT(request: Request) {}
export async function PATCH(request: Request) {}
export async function DELETE(request: Request) {}

 

메서드 예시

( 아래 예시에서는 address를 query로 받아서 처리 했는데

실제로는 address는 개인정보이므로 post 메서드를 사용하여 body에 값을 넣어 보내는 방식이 더 안전하다 )

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const id = searchParams.get('address');

  return NextResponse.json({ address });
}

export async function POST(request: Request) {
  const body = await request.json();
  const { address } = body;

  return NextResponse.json({ address });
}

 

클라이언트 호출 예시

fetch('/api/geocode?address=종로구 효자로 100');

fetch('/api/geocode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ address: '종로구 효자로 100' }),
});

 

• Pages router 방식

Pages router는 App router와 다르게 하나의 핸들러에서 모든 메서드를 처리한다. 직접 분기해야 한다는 수고가 있다.

// pages/api/geocode.ts
export default function handler(req, res) {
  if (req.method === 'POST') {
    ...
  }
  else if (req.method === 'GET') {
  	...
  }
}

 

3. 에러 처리 

App router 기준으로 설명

import { NextResponse } from 'next/server';
import axios from 'axios';

export async function POST(req: Request) {
  try {
    const { address } = await req.json();

    if (!address) {
      return NextResponse.json(
        { message: 'address is required' },
        { status: 400 }
      );
    }

    const response = await axios.get('외부 API URL', {
      params: {
        query: address,
      },
      headers: {
        // 예시 (네이버 API라면)
        // 'X-NCP-APIGW-API-KEY-ID': process.env.NAVER_CLIENT_ID!,
        // 'X-NCP-APIGW-API-KEY': process.env.NAVER_CLIENT_SECRET!,
      },
    });

    return NextResponse.json(response.data);

  } catch (error: any) {
    console.error('[GEOCODE_ERROR]', error);

    // axios 에러 구분 처리 (중요)
    if (axios.isAxiosError(error)) {
      return NextResponse.json(
        {
          message: 'External API error',
          detail: error.response?.data,
        },
        { status: error.response?.status ?? 502 }
      );
    }

    return NextResponse.json(
      { message: 'Internal Server Error' },
      { status: 500 }
    );
  }
}