GraphQL의 정의
GraphQL은 페이스북(現 메타)이 개발한 API를 위한 쿼리 언어이자 런타임입니다. 클라이언트가 필요한 데이터의 모양을 직접 정의해서 요청하면, 서버는 그 요청에 정확히 맞는 데이터만 응답으로 돌려줍니다. REST가 정해진 엔드포인트(예: ‘/users/1’, ‘/users/1/posts’)를 통해 고정된 형태의 데이터를 주고받는 방식이라면, GraphQL은 단 하나의 엔드포인트(보통 ‘/graphql’)에서 클라이언트가 원하는 필드만 골라서 요청하는 방식입니다.
비유하자면 REST는 정해진 메뉴판대로만 주문할 수 있는 식당이고, GraphQL은 ‘이 재료들로 이렇게 만들어주세요’라고 직접 요청할 수 있는 맞춤 주문에 가깝습니다.
동작 원리와 예시
GraphQL 서버는 스키마(Schema)라는 것으로 어떤 데이터와 타입이 존재하는지 미리 정의합니다. 클라이언트는 이 스키마를 기반으로 쿼리를 작성해 필요한 필드만 요청합니다. 예를 들어 사용자 이름과 이메일만 필요하다면 다음과 같이 요청할 수 있습니다.
query { user(id: 1) { name email } }
이 요청에 대한 서버 응답도 딱 그만큼만 옵니다. REST였다면 ‘/users/1’ 엔드포인트가 이름, 이메일, 주소, 가입일 등 모든 필드를 한꺼번에 내려주는 경우가 많아서, 클라이언트가 필요 없는 데이터까지 받는 ‘오버페칭(Over-fetching)’이 발생하기 쉽습니다. 반대로 사용자 정보와 게시글 목록을 동시에 가져오려면 REST에서는 두 번의 요청(‘/users/1’과 ‘/users/1/posts’)이 필요한 ‘언더페칭(Under-fetching)’ 문제가 생기지만, GraphQL은 한 번의 쿼리로 두 데이터를 함께 요청할 수 있습니다.
실무에서 GraphQL을 쓰는 이유
모바일 앱처럼 네트워크 대역폭이 중요한 환경에서는 오버페칭을 줄이는 것만으로도 성능에 큰 도움이 됩니다. 또한 프론트엔드 화면 하나에 여러 도메인의 데이터가 섞여 있는 경우, 여러 REST API를 조합하는 대신 GraphQL 쿼리 하나로 필요한 데이터를 한 번에 받아올 수 있어 개발 생산성이 올라갑니다.
- 클라이언트 주도적 데이터 요청으로 오버/언더페칭 문제 완화
- 단일 엔드포인트로 API 버전 관리 부담 감소
- 스키마 기반이라 문서화와 타입 검증이 자동으로 이루어짐
물론 GraphQL이 REST를 완전히 대체하는 것은 아닙니다. 캐싱 전략이 REST보다 복잡하고, 서버 구현 난이도가 높아질 수 있어 서비스 특성에 맞게 선택하는 것이 중요합니다.