REST API vs GraphQL 차이점과 선택 기준

REST API와 GraphQL 차이, 핵심만 먼저 정리

REST API(Representational State Transfer, 자원을 URL 주소로 표현하고 HTTP 메서드로 조작하는 전통적인 API 설계 방식)는 기능마다 별도의 엔드포인트(endpoint, 요청을 받는 URL 주소)를 만듭니다. 반면 GraphQL(2015년 페이스북이 공개한 API용 쿼리 언어)은 단 하나의 엔드포인트에서 클라이언트가 원하는 데이터 구조를 직접 쿼리로 지정해 받아옵니다. 가장 큰 차이는 '누가 응답 구조를 결정하는가'입니다 — REST는 서버가, GraphQL은 클라이언트가 결정합니다.

실무에서는 어느 한쪽이 절대적으로 우월하지 않습니다. 서비스 규모, 클라이언트 종류(웹·모바일·서드파티), 팀의 캐싱 전략에 따라 선택이 달라집니다. 아래에서 구조적 차이부터 실무 선택 기준, 자주 하는 실수까지 순서대로 정리합니다.

REST API의 구조와 동작 방식

자원 중심 엔드포인트 설계

REST API는 '자원(resource)'을 URL로 표현하고, HTTP 메서드(GET·POST·PUT·DELETE)로 그 자원에 대한 동작을 구분합니다. 예를 들어 사용자와 사용자의 게시글 데이터를 가져오려면 아래처럼 여러 요청을 조합해야 하는 경우가 많습니다.


# 사용자 정보 조회
curl https://api.example.com/users/1

# 해당 사용자의 게시글 목록 조회
curl https://api.example.com/users/1/posts

# 특정 게시글의 댓글 조회
curl https://api.example.com/posts/42/comments

화면 하나를 그리기 위해 여러 엔드포인트를 순차 또는 병렬로 호출해야 하는 구조라, 화면 요구사항이 바뀔 때마다 새 엔드포인트를 추가하거나 기존 응답에 필드를 끼워 넣는 일이 반복됩니다. 서비스가 커질수록 엔드포인트 수가 기하급수적으로 늘어나는 것이 REST의 대표적인 관리 부담입니다.

오버페칭과 언더페칭 문제

REST는 엔드포인트 하나가 고정된 응답 구조를 돌려주기 때문에, 화면에 필요한 필드가 3개뿐이어도 서버가 정해놓은 10개 필드를 통째로 받는 오버페칭(overfetching)이 흔합니다. 반대로 화면에 필요한 데이터가 여러 자원에 걸쳐 있으면 엔드포인트를 여러 번 호출해야 하는 언더페칭(underfetching)도 발생합니다. 모바일 환경처럼 네트워크 비용이 민감한 서비스일수록 이 비효율이 체감됩니다.

GraphQL의 구조와 동작 방식

스키마와 타입 시스템

GraphQL 서버는 먼저 스키마(schema)를 정의합니다. 어떤 타입의 데이터가 존재하고, 타입 간에 어떤 관계가 있는지를 명세한 것입니다. 클라이언트는 이 스키마를 기준으로 자신이 원하는 필드만 골라 쿼리를 작성합니다.


query {
  user(id: "1") {
    name
    posts {
      title
      comments {
        content
      }
    }
  }
}

위 쿼리 하나로 사용자 이름, 게시글 제목, 댓글 내용까지 단일 요청으로 받아옵니다. 서버는 각 필드를 처리하는 리졸버(resolver, 필드별 데이터를 실제로 가져오는 함수)를 통해 응답을 조립해 아래와 같은 JSON을 돌려줍니다.


{
  "data": {
    "user": {
      "name": "홍길동",
      "posts": [
        { "title": "첫 글", "comments": [{ "content": "좋아요" }] }
      ]
    }
  }
}

단일 엔드포인트와 쿼리 조합

GraphQL은 조회에는 query, 데이터 변경에는 mutation(뮤테이션)이라는 별도 연산을 사용하지만, 둘 다 같은 하나의 엔드포인트(보통 /graphql)로 요청을 보냅니다. 엔드포인트를 늘리지 않고도 기능을 추가할 수 있다는 점이 REST와 가장 대비되는 부분입니다.

GraphQL은 요청 처리 중 오류가 나도 HTTP 상태 코드를 200으로 반환하고, 응답 본문의 errors 필드에 오류 내용을 담는 경우가 많습니다. REST의 4xx·5xx 상태 코드 기반 에러 처리에 익숙하다면 클라이언트 쪽 에러 핸들링 로직을 별도로 구현해야 한다는 점을 놓치기 쉽습니다.

REST API vs GraphQL 핵심 차이 5가지

비교 항목	REST API	GraphQL
엔드포인트	자원마다 다수	단일 엔드포인트
응답 데이터	서버가 구조 고정	클라이언트가 필드 선택
오버·언더페칭	발생 빈도 높음	필요한 만큼만 요청해 감소
캐싱	HTTP 캐시(URL 기준) 활용 쉬움	URL이 고정이라 별도 캐싱 전략 필요
학습·운영 부담	상대적으로 낮음	스키마·리졸버 설계 학습 필요

REST는 URL 자체가 자원을 식별하므로 브라우저·CDN의 HTTP 캐시를 그대로 활용할 수 있지만, GraphQL은 대부분 POST 요청이라 URL 기반 캐싱이 어렵습니다.
REST는 명세(OpenAPI/Swagger 등)를 별도로 관리해야 하지만, GraphQL은 스키마 자체가 문서 역할을 겸해 API 탐색 도구(GraphiQL 등)에서 바로 확인할 수 있습니다.

실무에서는 언제 무엇을 선택해야 할까

REST API가 유리한 경우

단순한 CRUD(Create·Read·Update·Delete) 위주의 서비스, 캐싱 효율이 중요한 공개 API, 팀 내에 GraphQL 운영 경험이 없는 경우에는 REST가 여전히 합리적인 선택입니다. HTTP 표준을 그대로 따르기 때문에 학습 곡선이 낮고, 기존 인프라(리버스 프록시, CDN 캐시)와 궁합이 좋습니다.

실제로 외부 API를 연동할 때도 이 차이가 체감됩니다. REST 기반 AI API는 요청마다 고정된 엔드포인트와 응답 구조를 따르는 경우가 많아 필요한 필드만 골라 요청하기가 상대적으로 까다롭습니다.

GraphQL이 유리한 경우

화면마다 필요한 데이터 구성이 자주 바뀌는 프론트엔드 중심 서비스, 웹·모바일·태블릿처럼 클라이언트 종류가 다양해 화면별로 응답 구조가 달라야 하는 경우, 여러 마이크로서비스의 데이터를 한 화면에 조합해야 하는 경우에 GraphQL의 장점이 뚜렷합니다.

현재 화면 요구사항이 얼마나 자주, 크게 바뀌는지 점검합니다.
클라이언트 종류(웹 전용인지, 멀티 플랫폼인지)를 확인합니다.
팀에 스키마·리졸버 설계, N+1 문제 대응 경험이 있는지 확인합니다.
기존 인프라(캐시, 모니터링, 인증)를 GraphQL로 전환하는 데 드는 비용을 REST 유지 비용과 비교합니다.

도입 시 흔히 하는 실수와 주의점

GraphQL을 무조건 '더 발전된 기술'로 오해해 REST를 통째로 대체하려다 운영 부담만 늘리는 경우가 많습니다. 아래 항목을 도입 전에 점검하는 것이 좋습니다.

N+1 문제: 하나의 쿼리가 관계 데이터를 조회할 때 리졸버가 반복 호출되어 수십~수백 번의 데이터베이스 쿼리를 유발할 수 있습니다. DataLoader 같은 배치·캐싱 도구로 대응해야 합니다.
쿼리 복잡도 제한 누락: 클라이언트가 지나치게 깊거나 넓은 쿼리를 보내면 서버 자원을 과도하게 소모할 수 있어, 쿼리 깊이·복잡도 제한을 서버 단에서 반드시 설정해야 합니다.
REST식 캐싱을 그대로 기대: URL 기반 HTTP 캐시가 동작하지 않으므로 클라이언트 캐싱 라이브러리(Apollo Client, Relay 등)나 서버 측 응답 캐싱을 별도로 구축해야 합니다.
부분 도입 전략 부재: 기존 REST API를 한 번에 GraphQL로 바꾸기보다, 신규 기능이나 데이터 조합이 잦은 화면부터 점진적으로 도입하는 팀이 안정적으로 정착하는 경우가 많습니다.

자주 묻는 질문

Q. GraphQL이 REST API를 완전히 대체하나요?

아니요. 두 방식은 상호 대체보다 병행 사용되는 경우가 많습니다. 파일 업로드, 단순 조회 위주의 공개 API는 REST를 유지하고, 복잡한 화면 데이터 조합이 필요한 부분만 GraphQL로 도입하는 하이브리드 구조가 실무에서 흔합니다.

Q. GraphQL은 REST보다 항상 더 빠른가요?

아닙니다. 요청 횟수를 줄여주는 것이지 응답 자체의 처리 속도를 보장하지 않습니다. 리졸버 설계가 비효율적이면 N+1 문제로 오히려 REST보다 데이터베이스 부하가 커질 수 있습니다.

Q. 작은 프로젝트에도 GraphQL을 도입해야 할까요?

단순한 CRUD 위주의 소규모 프로젝트라면 REST API만으로 충분한 경우가 대부분입니다. 스키마 설계, 리졸버 구현, 쿼리 복잡도 제한 등 GraphQL 고유의 운영 비용을 감당할 만큼 화면 요구사항이 복잡할 때 도입을 검토하는 것이 합리적입니다.

Q. REST API와 GraphQL을 같은 서버에서 함께 쓸 수 있나요?

가능합니다. 같은 백엔드에서 REST 엔드포인트와 GraphQL 엔드포인트를 동시에 노출하고, 프론트엔드가 상황에 맞는 방식을 선택해 호출하는 구조는 실제 서비스에서 자주 쓰입니다.

Q. GraphQL 도입 전에 꼭 확인해야 할 것은 무엇인가요?

쿼리 깊이·복잡도 제한, N+1 문제 대응 전략(DataLoader 등), 캐싱 전략, 인증·권한 처리 방식을 먼저 설계해야 합니다. 이 네 가지를 준비하지 않고 도입하면 오히려 REST보다 운영이 어려워질 수 있습니다.