GraphQL vs. REST: 어떤 API 스타일을, 언제 써야 할까?

REST는 고정된 엔드포인트가 많은 API 스타일이고, GraphQL은 클라이언트가 단일 엔드포인트에 필요한 필드만 요청하는 쿼리 언어입니다. 이 비교의 본질은 누가 응답의 모양을 결정하는가입니다. REST에서는 서버가 설계 시점에 결정했고, GraphQL에서는 클라이언트가 요청마다 결정합니다. 캐싱, 버전 관리, 오류, 성능 등 나머지 모든 것은 이 하나의 역전에서 따라 나옵니다.

핵심 요약

같은 화면, 두 가지 방식

프로필 화면에는 사용자, 그 사용자의 최신 게시물 5개, 팔로워 수가 필요합니다. REST는 리소스 단위로 말합니다:

GET /users/42               → 필드 38개, 필요한 것은 3개  (오버페칭)
GET /users/42/posts?limit=5 → 두 번째 왕복                (언더페칭)
GET /users/42/followers     → 세 번째 왕복

GraphQL은 모양을 갖춘 질문 하나로 말합니다:

POST /graphql
query {
  user(id: 42) {
    name
    avatarUrl
    posts(first: 5) { title likes }
    followers { totalCount }
  }
}
→ 왕복 한 번, 정확히 그 필드만, 그 외에는 아무것도 없음

실제 격차는 흔히 말하는 것보다 좁습니다. 잘 설계된 REST도 필드 선택을 지원하며, SDK 쿼리 빌더를 쓰면 필드 선택이 기본 습관이 됩니다:

// JavaScript / Node.js — Back4app JS SDK
// GraphQL's best trick — ask only for what you need — without leaving REST
const query = new Parse.Query('Article');
query.equalTo('status', 'published');
query.select('title', 'views');        // field selection, GraphQL-style
const articles = await query.find();   // lean payload over the REST API
// The same backend also speaks real GraphQL: query { articles { ... } }

// Flutter / Dart — Back4app Flutter SDK
// GraphQL's best trick — ask only for what you need — without leaving REST
final query = QueryBuilder<ParseObject>(ParseObject('Article'))
  ..whereEqualTo('status', 'published')
  ..keysToReturn(['title', 'views']);   // field selection, GraphQL-style
final response = await query.query();   // lean payload over the REST API

// iOS / Swift — Back4app Swift SDK
// GraphQL's best trick — ask only for what you need — without leaving REST
let query = Article.query("status" == "published")
  .select("title", "views")             // field selection, GraphQL-style
query.find { result in
  if case .success(let articles) = result { render(articles) }
}

// Android / Kotlin — Back4app Android SDK
// GraphQL's best trick — ask only for what you need — without leaving REST
val query = ParseQuery.getQuery<ParseObject>("Article")
query.whereEqualTo("status", "published")
query.selectKeys(listOf("title", "views"))  // field selection, GraphQL-style
query.findInBackground { articles, e -> if (e == null) render(articles) }

한눈에 보는 GraphQL vs. REST

비교 글들이 건너뛰는 부분

N+1 문제는 자리를 옮겼을 뿐 사라지지 않았습니다. 작성자를 포함한 게시물을 요청하는 GraphQL 쿼리를 단순하게 구현하면 게시물마다 리졸버 호출이 한 번씩 발생합니다. ORM 때문에 널리 알려진 바로 그 N+1 문제가 이제 서버 측에서 일어나는 것입니다. 표준 치료법은 배칭입니다. 요청마다 로더가 작성자 ID를 모아 쿼리 한 번으로 가져옵니다. 배칭 전략 없이 GraphQL을 도입하면 REST의 최악의 성능 버그를 자리만 옮겨 그대로 들여오는 셈입니다.

오류는 운영상의 결정입니다. “errors 배열을 담은 200”은 상태 코드를 기준으로 만든 대시보드, 알림, CDN 로직이 기본적으로 오류를 감지하지 못한다는 뜻입니다. GraphQL로 성공하는 팀은 오류 관측 가능성을 나중에 생각할 일이 아니라 도입의 일부로 다룹니다.

제한 없는 쿼리에는 제한이 필요합니다. 유연한 엔드포인트 하나는 쿼리 하나가 그래프 전체를 순회할 수 있다는 뜻입니다. 공식 보안 지침은 깊이 제한, 쿼리 비용 예산, 그리고 자사 클라이언트를 위한 영속 쿼리 허용 목록을 권장합니다. REST의 고정된 엔드포인트는 비용 제어를 암묵적으로 해 주었지만, GraphQL은 그것을 사용자의 일로 만듭니다.

일반적인 사용 사례

• GraphQL: 느린 네트워크의 모바일 앱, 많은 엔티티를 엮는 대시보드, 웹 + 모바일 + 파트너 클라이언트의 데이터 요구가 갈라지는 제품, 안정적인 스키마 위에서의 빠른 프론트엔드 반복.
• REST: 공개 개발자 API, 캐시 가능한 콘텐츠 전달, 웹훅과 연동 표면, 파일 전송, 단순성이 이기는 서비스 간 호출.
• 둘 다(엔터프라이즈의 표준): 백엔드 서비스 사이에는 REST나 RPC, 프론트엔드를 위해 이를 집계하는 GraphQL 계층. 스키마를 갖춘 백엔드 포 프론트엔드 패턴입니다.

GraphQL과 REST 중 무엇을 선택해야 할까? 결정 매트릭스

솔직한 기본값은 이렇습니다. REST로 시작하고, 다중 클라이언트의 데이터 모양 문제가 실제로 닥쳤을 때 GraphQL을 추가하는 것입니다. 그리고 플랫폼이 스키마 하나에서 둘 다 생성해 준다면, 이 선택은 아키텍처의 문제가 아니라 요청마다 하는 선택이 됩니다.

한계와 트레이드오프

• REST: 데이터 밀도 높은 화면에서의 오버/언더페칭, 버전 마이그레이션, 팀 사이의 응답 모양 표류, 그리고 N개 엔드포인트의 문서.
• GraphQL: 캐싱에는 별도 메커니즘이, 비용 제어에는 지속적인 감시가, 리졸버에는 배칭 규율이, 그리고 errors를 담은 200 패턴에는 관측 가능성 재작업이 필요합니다.
• 둘 다: 어느 쪽도 나쁜 데이터 모델을 고치지 못합니다. 혼란스러운 도메인은 어떤 스타일에서든 혼란스러운 API를 만듭니다. REST 박사 논문 자체가 조용히 암시하듯, 제약 조건은 언제나 그 아래의 아키텍처에 관한 것이었습니다.

Back4app에서의 GraphQL과 REST

Back4app은 관리형 데이터베이스, 자동 생성되는 REST 및 GraphQL API, 인증, 파일 스토리지, Cloud Code 서버리스 함수를 결합한 오픈소스 Backend as a Service(BaaS) 플랫폼입니다. 이 글의 딜레마를 뿌리에서 해소합니다. 두 API 스타일이 같은 스키마에서 생성됩니다. URL 캐싱이 가능한 REST 엔드포인트와 중첩 쿼리를 갖춘 타입 있는 GraphQL API에 더해, 필드 선택(위의 코드 탭)으로 어느 전송 방식에서든 GraphQL의 대표 이점을 제공하는 SDK까지 갖춥니다. 클라이언트마다 고르고, 화면마다 바꾸고, API 계층은 전혀 작성하지 않아도 됩니다.