웹개발 API, REST와 GraphQL을 둘 다 써본 차이

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

상품 목록 화면에 필터 하나를 추가했을 뿐인데 API 응답과 프론트엔드 코드를 함께 고쳐야 했습니다. 반대로 다른 프로젝트에서는 GraphQL을 도입했다가 단순한 조회 기능에도 스키마와 리졸버, 캐시 정책까지 신경 쓰느라 개발 속도가 오히려 느려졌습니다. 두 경험을 거치고 나니 REST와 GraphQL의 차이는 기능의 우열보다 팀이 감당할 복잡성을 어디에 둘 것인가에 가깝다는 판단이 들었습니다.

저는 REST를 사내 관리 도구와 쇼핑몰 백엔드에, GraphQL을 여러 화면이 같은 데이터를 서로 다른 형태로 소비하는 콘텐츠 서비스에 적용했습니다. 아래 내용은 문법을 소개하는 이론 수업이 아니라, 실제 웹개발 과정에서 겪은 장단점과 선택 기준을 중심으로 풀어낸 사용 후기입니다.

REST는 단순했고 GraphQL은 화면 변화에 강했습니다

REST로 빠르게 시작했을 때 좋았던 점

첫 번째 프로젝트는 사용자, 주문, 상품을 관리하는 내부 웹서비스였습니다. 자원이 명확해서 GET /users, GET /orders/:id, POST /products처럼 엔드포인트를 나누기 쉬웠고, 새로 합류한 개발자도 주소와 HTTP 메서드만 보고 기능을 짐작했습니다. Postman으로 요청을 재현하거나 서버 로그에서 문제의 경로를 찾는 과정도 직관적이었습니다.

특히 브라우저와 CDN의 HTTP 캐시를 활용하기 편했습니다. 변경이 드문 카테고리 목록에는 캐시 헤더를 설정했고, 장애가 발생했을 때는 특정 엔드포인트의 응답 시간만 추적하면 됐습니다. CRUD 중심 웹개발이라면 REST가 제공하는 예측 가능성 자체가 생산성이었습니다. 프로그래밍의 기본 개념이 낯설다면 프로그래밍 용어 정의를 먼저 확인하면 요청, 처리, 출력의 관계를 이해하는 데 도움이 됩니다.

• 장점: URL 구조가 명확해 로그 분석과 권한 설정이 쉬웠습니다.
• 장점: HTTP 상태 코드와 캐시 기능을 그대로 활용할 수 있었습니다.
• 단점: 화면별 요구 데이터가 달라지면 전용 엔드포인트가 빠르게 늘었습니다.
• 단점: 목록 응답에 필요 없는 필드가 포함되는 과다 조회가 생겼습니다.

GraphQL로 바꾼 뒤 체감한 차이

콘텐츠 서비스에서는 한 화면에 작성자, 게시물, 댓글 수, 추천 상태가 함께 필요했습니다. REST 방식으로는 네 번 요청하거나 화면 전용 조합 API를 만들어야 했지만, GraphQL에서는 클라이언트가 필요한 필드를 한 쿼리에 선언할 수 있었습니다. 모바일 화면이 작성자 소개를 빼더라도 서버 응답 모델을 새로 만들 필요가 없었습니다.

그러나 요청 횟수가 줄었다고 서버 부하까지 자동으로 감소하지는 않았습니다. 댓글 목록의 각 항목에서 작성자를 개별 조회하는 N+1 문제가 발생했고, 한 번의 HTTP 요청 내부에서 데이터베이스 쿼리가 수십 번 실행됐습니다. DataLoader로 조회를 묶고 쿼리 깊이 제한을 적용한 뒤에야 안정적인 응답 시간을 얻었습니다.

사용 팁: GraphQL의 요청 한 번을 데이터베이스 조회 한 번으로 착각하면 안 됩니다. 운영 전 리졸버별 호출 횟수와 실제 SQL 개수를 반드시 함께 기록해 보세요.

GraphQL 도입 후 코딩보다 운영에서 더 많이 배웠습니다

스키마와 캐시는 생각보다 오래 남았습니다

처음에는 GraphQL의 가장 큰 매력을 프론트엔드 개발자가 원하는 데이터를 자유롭게 가져가는 데서 찾았습니다. 실제로 화면 개발 속도는 빨라졌지만, 시간이 지나자 공개된 스키마가 일종의 계약으로 남았습니다. 사용 중인 필드를 바로 삭제할 수 없어 deprecated 표시를 하고, 클라이언트 사용량을 확인한 뒤 제거해야 했습니다.

캐시도 REST보다 더 많은 판단을 요구했습니다. 모든 요청이 같은 경로로 들어오기 때문에 URL만으로 응답을 저장하기 어렵고, 객체의 타입과 ID를 기준으로 정규화해야 했습니다. Apollo Client를 사용할 때 동일한 게시물이 서로 다른 쿼리에서 반환돼도 하나의 객체로 합쳐지는 점은 편했지만, 페이지네이션 병합 정책을 잘못 작성해 목록이 중복되는 버그도 경험했습니다.

1. 스키마 이름부터 합의했습니다. 화면 이름이 아니라 비즈니스 개념을 기준으로 타입을 만들었습니다.
2. 쿼리 복잡도를 제한했습니다. 깊게 중첩된 요청이 서버 자원을 독점하지 않도록 깊이와 비용을 계산했습니다.
3. 영속 쿼리를 적용했습니다. 허용된 쿼리의 해시를 등록해 임의의 고비용 요청을 줄였습니다.
4. 필드 사용량을 기록했습니다. 사용되지 않는 필드를 감으로 삭제하지 않고 실제 호출 데이터를 확인했습니다.
5. 페이지네이션 규칙을 통일했습니다. 데이터가 자주 바뀌는 목록에는 커서 방식을 우선 적용했습니다.

작은 실험으로 비용을 먼저 드러냈습니다

두 번째 GraphQL 도입 때는 전체 API를 한꺼번에 전환하지 않았습니다. 요구사항이 자주 바뀌는 홈 피드 조회만 GraphQL로 만들고, 로그인과 파일 업로드는 기존 REST를 유지했습니다. 3주 동안 응답 크기, 데이터베이스 쿼리 수, 프론트엔드 수정 시간, 오류 추적 시간을 기록하니 팀이 얻는 이점과 부담이 숫자로 드러났습니다.

예를 들어 홈 피드의 평균 전송량은 필요한 필드만 선택하면서 약 35% 줄었지만, 백엔드의 초기 구현 시간은 REST 예상치보다 약 이틀 더 들었습니다. 반면 이후 카드 UI가 세 차례 바뀌는 동안 서버 DTO 수정은 거의 없었습니다. 여러분의 서비스도 출시 직후 화면 실험이 반복되나요? 그렇다면 초기 이틀보다 이후 변경 비용의 감소가 더 큰 가치일 수 있습니다.

코딩은 명령을 나열하는 작업을 넘어 문제를 절차로 바꾸는 과정입니다. 코딩의 기본 의미를 살펴보면, API 기술을 고를 때도 유행보다 해결하려는 문제를 먼저 정의해야 하는 이유가 선명해집니다.

새 기술의 검증 기간에는 평균 응답 시간만 보지 말고 95백분위 응답 시간, 쿼리 수, 장애 재현 시간, 기능 변경에 든 시간을 함께 측정하는 편이 좋습니다.

모든 화면을 한 방식으로 통일하지 않아도 됐습니다

제가 지금 적용하는 현실적인 선택 기준

실무에서 가장 효과적이었던 방법은 REST와 GraphQL 중 하나를 조직의 표준으로 선언하는 것이 아니라, 경계가 분명한 곳에 각각 배치하는 것이었습니다. 인증 토큰 발급, 웹훅 수신, 파일 업로드처럼 입력과 결과가 명확한 기능은 REST가 단순했습니다. 여러 데이터가 얽히고 클라이언트별 화면 구성이 다른 조회 영역은 GraphQL의 유연성이 빛났습니다.

새 프로젝트를 시작할 때는 먼저 소비자를 셉니다. 웹 한 종류만 있고 화면 변화가 적다면 REST로도 충분합니다. 웹, 모바일 앱, 파트너 대시보드가 같은 데이터를 서로 다른 모양으로 요청한다면 GraphQL을 검토할 이유가 생깁니다. 다만 팀에 스키마 설계와 성능 관찰을 맡을 사람이 없다면 자유로운 쿼리가 운영 위험으로 돌아올 수 있습니다.

• REST를 먼저 선택할 상황: 단순 CRUD, 짧은 출시 일정, HTTP 캐시 비중이 큰 공개 콘텐츠, 소규모 개발팀입니다.
• GraphQL을 검토할 상황: 클라이언트가 여러 개이고 화면별 데이터 조합이 자주 달라지는 서비스입니다.
• 혼합 구성이 유리한 상황: 조회 화면은 복잡하지만 인증, 업로드, 외부 연동은 규격이 고정된 서비스입니다.
• 도입을 미룰 상황: 느린 원인이 API 형식이 아니라 인덱스 누락이나 비효율적인 SQL에 있는 경우입니다.

그래도 REST 하나로 통일하자는 의견이 타당할 때

팀원이 적고 운영 시간이 부족하다면 REST 하나로 통일하자는 반대 의견은 충분히 합리적입니다. 기술 종류가 늘어나면 인증, 오류 형식, 모니터링, 문서화 방식도 두 벌이 될 수 있습니다. GraphQL이 프론트엔드의 변경 비용을 낮추더라도 백엔드와 인프라 담당자의 인지 부담이 더 커진다면 전체 생산성은 떨어집니다.

저 역시 사내 관리자 화면에서는 GraphQL 전환 제안을 철회한 적이 있습니다. 화면 수가 적고 API 소비자가 하나뿐이라 얻을 수 있는 이익이 작았기 때문입니다. 대신 REST 응답에 필드 선택 파라미터를 제한적으로 추가하고, OpenAPI 문서를 자동 생성해 불편을 줄였습니다. 도구를 추가하지 않고 현재 구조를 개선하는 선택도 훌륭한 개발 결정입니다.

반대로 REST 엔드포인트가 화면 이름을 따라 계속 생기고, 모바일과 웹의 요구 차이를 맞추느라 배포가 묶인다면 작은 GraphQL 조회 영역부터 시험해 볼 만합니다. 이때 성공 기준은 최신 기술을 사용했다는 사실이 아니라, 기능 변경 시간이 실제로 줄고 운영자가 쿼리 비용을 설명할 수 있는지입니다. 결국 REST와 GraphQL 사이의 선택은 취향 대결이 아니라 현재 팀이 어느 복잡성을 더 잘 관리할 수 있는가에 대한 답이어야 합니다.