REST API vs GraphQL, 뭘 선택해야 할까

새 프로젝트를 시작할 때 API 설계 방식으로 REST와 GraphQL 중 무엇을 선택할지 고민하는 경우가 많습니다. 두 방식 모두 훌륭하지만, 상황에 따라 적합한 선택이 다릅니다. 각각의 특징을 이해하고 올바른 선택을 해봅시다.

REST API란?

REST(Representational State Transfer)는 URL로 리소스를 나타내고 HTTP 메서드(GET, POST, PUT, DELETE)로 동작을 표현하는 아키텍처 스타일입니다.

# 사용자 목록 조회
GET /api/users

# 특정 사용자 조회
GET /api/users/1

# 사용자 생성
POST /api/users
Content-Type: application/json
{ "name": "홍길동", "email": "hong@example.com" }

# 사용자 수정
PUT /api/users/1
{ "name": "홍길순" }

# 사용자 삭제
DELETE /api/users/1

GraphQL이란?

GraphQL은 Facebook이 개발한 쿼리 언어입니다. 클라이언트가 필요한 데이터를 정확히 명시해서 요청할 수 있습니다. 단 하나의 엔드포인트(/graphql)로 모든 요청을 처리합니다.

# 필요한 필드만 정확히 요청
query GetUser {
  user(id: 1) {
    name
    email
    posts {
      title
      createdAt
    }
  }
}

# 뮤테이션 (데이터 변경)
mutation CreateUser {
  createUser(input: { name: "홍길동", email: "hong@example.com" }) {
    id
    name
  }
}

핵심 차이점 비교

항목	REST	GraphQL
엔드포인트	리소스마다 별도 URL	단일 엔드포인트
데이터 요청	서버가 응답 형태 결정	클라이언트가 필요한 필드 지정
Over-fetching	발생 가능	없음
Under-fetching	발생 가능 (N+1 문제)	한 번에 해결
캐싱	HTTP 캐싱 기본 지원	별도 설정 필요
학습 곡선	낮음	높음
파일 업로드	쉬움	추가 설정 필요

REST가 적합한 경우

• 간단한 CRUD 서비스
• 퍼블릭 API (외부 개발자가 사용하는 경우)
• HTTP 캐싱이 중요한 경우
• 팀이 REST에 익숙한 경우
• 파일 업로드가 핵심 기능인 경우

GraphQL이 적합한 경우

• 모바일 앱처럼 네트워크 효율이 중요한 클라이언트
• 다양한 클라이언트(웹, 앱, 서드파티)가 동일 API를 사용하는 경우
• 복잡하게 연결된 데이터 구조 (소셜 네트워크, 추천 시스템)
• 프론트엔드 팀이 API 스펙을 자율적으로 관리해야 하는 경우

실전 예시: 블로그 API

블로그 게시글 목록 페이지에서 작성자 정보도 함께 보여야 한다면:

// REST — 2번의 요청 필요 (N+1 문제)
const posts = await fetch('/api/posts').then(r => r.json());
const authors = await Promise.all(
  posts.map(p => fetch(`/api/users/${p.authorId}`).then(r => r.json()))
);

// GraphQL — 1번의 요청으로 해결
const { data } = await fetch('/graphql', {
  method: 'POST',
  body: JSON.stringify({
    query: `{
      posts {
        title
        author { name avatar }
        createdAt
      }
    }`
  })
});