쉬운 설명
전통적인 REST API에서는 사용자 정보를 받으려면 /users/123에 요청하고, 그 사용자의 글 목록을 보려면 또 /users/123/posts에 요청해야 합니다. 화면 하나 그리려고 서버에 네다섯 번씩 다녀와야 하는 일이 흔합니다. 모바일 환경에서는 네트워크 비용이 그대로 사용자 체감 속도가 됩니다.
GraphQL은 이걸 한 번에 끝낼 수 있게 해 줍니다. 클라이언트가 '나는 사용자의 이름과 그 사용자의 최신 글 3개의 제목만 필요해'라고 쿼리를 보내면, 서버가 정확히 그 모양의 응답을 돌려줍니다. 불필요한 필드는 빠지고, 여러 리소스를 한 번에 조합해서 받습니다.
동작 흐름은 세 단계입니다. ① 서버는 '이 시스템엔 이런 타입(User·Post·Comment)이 있고, 각 타입엔 이런 필드가 있다'는 스키마를 정의. ② 클라이언트는 그 스키마 안에서 자기 화면에 필요한 데이터의 모양을 적어 쿼리로 보냄. ③ 서버는 쿼리를 분석해 필요한 리소스를 조합한 응답을 돌려줌. 스키마가 강력한 타입 시스템 역할을 해서 도구·자동완성이 풍부합니다.
강점은 분명합니다. ① 한 번 요청으로 필요한 모든 정보 — 화면 한 장을 그리기 좋음. ② 응답이 화면에 딱 맞아 데이터 낭비가 적음. ③ 스키마 덕분에 IDE 자동완성·문서 자동 생성 등 개발자 경험이 좋음. 페이스북에서 시작해 깃허브·쇼피파이·인스타카트 같은 곳에서 표준이 됐습니다.
단점도 무시할 수 없습니다. 서버 구현이 REST보다 까다롭고, 캐싱이 (각 쿼리가 고유한 형태라서) 단순하지 않습니다. 또 잘못 짜면 한 쿼리가 DB를 과도하게 두드리는 'N+1' 문제가 생깁니다. 그래서 작은 서비스에 GraphQL을 도입하는 건 과한 선택일 수 있습니다 — '화면이 많고 클라이언트가 여러 가지(웹·iOS·안드로이드)다'일 때 가장 효용이 큽니다.
비유로 보면
REST는 정해진 세트 메뉴를 시키는 식당, GraphQL은 뷔페에서 원하는 것만 골라 담는 식당과 비슷합니다. 세트 메뉴는 단순하지만 안 먹는 반찬도 함께 받습니다. 뷔페는 정확히 먹을 만큼만 가져오지만, 주방이 어떻게 그 모든 조합을 동시에 준비할 수 있게 설계하는지가 더 복잡한 일입니다.
어디에서 만나나
모바일·태블릿·웹 등 여러 클라이언트를 동시에 운영하는 서비스, 화면이 자주 바뀌고 각각 다른 데이터가 필요한 SaaS, 외부 개발자에게 풍부한 API를 공개하고 싶은 플랫폼(깃허브·쇼피파이)에서 진가가 큽니다. 작은 단일 백엔드+단일 프런트엔드 조합에서는 REST가 여전히 더 가볍습니다.
작은 예시
쇼핑 앱 메인 화면이 추천 상품·진행 중인 주문·새 알림을 한 번에 보여 줘야 한다고 해 봅시다. REST라면 세 번 요청해야 하지만, GraphQL이라면 세 가지를 한 쿼리에 적어서 한 번에 받아 화면을 빠르게 그릴 수 있습니다.
자주 하는 오해
한 줄 정리
GraphQL의 매력은 '클라이언트가 원하는 모양을 선언한다'는 데 있습니다. 클라이언트가 많고 화면이 자주 바뀌는 회사라면 충분히 검토해 볼 만한 도구입니다.