API 설계 원칙 — REST vs GraphQL, 실무에서 선택한 기준
두 진영의 대립에서 찾은 균형
2023년 말, 우리 회사의 백엔드 팀 회의는 치열했다. 새로운 API를 설계할 때 REST를 써야 한다는 팀과 GraphQL을 써야 한다는 팀이 대립했다. 결론: REST는 공개 API에, GraphQL은 내부 API에 사용하기로 결정했다. 경험상 이게 최고의 결정이었다. 프레임워크 선택과 마찬가지로, API 설계도 "팀이 효율적으로 관리할 수 있는 것"이 첫 번째 조건이다. REST의 간단함이 필요한가, 아니면 GraphQL의 유연함이 필요한가. 두 가지를 동시에 지원할 수도 있다는 게 핵심이다.
REST의 진정한 가치
REST는 성숙도가 있다. Richardson Maturity Model에 따르면 4단계가 있다. 0단계에서는 HTTP를 단순 전송으로만 사용하고, 1단계에서 리소스 개념을 도입한다. 2단계에서는 HTTP 메서드를 제대로 사용하며, 3단계는 HATEOAS를 구현한다. 대부분의 실무 API는 2-3단계 초반에 있다. 완전한 HATEOAS는 복잡도가 높아 실제로는 드물다. 우리가 성공한 REST API들의 공통점은 리소스 중심 설계, 일관된 에러 응답, 체계적인 페이지네이션, 명확한 버전 관리였다. REST는 캐싱이 간단하고 디버깅도 쉽다. curl로 바로 테스트할 수 있으니까.
GraphQL의 진정한 가치
GraphQL은 REST와 완전히 다른 철학이다. 클라이언트가 필요한 데이터를 명시적으로 지정해서 요청한다. 이렇게 하면 over-fetching(불필요한 데이터 수신)과 under-fetching(여러 API 호출 필요)을 모두 방지할 수 있다. 특히 모바일 앱에서는 네트워크 효율이 중요하니 GraphQL이 유리하다. 또한 강력한 타입 시스템이 있어서 TypeScript와 자동으로 타입을 동기화할 수 있다. 하지만 GraphQL도 단점이 있다. 학습 곡선이 가파르고, 캐싱이 복잡하며, N+1 쿼리 문제가 발생하기 쉽다. 관리 부담이 높다는 게 가장 큰 문제다.
우리의 결정
공개 API는 REST로, 내부 API는 GraphQL로. 이게 우리의 최종 선택이었다. 공개 API는 외부 개발자들이 사용하므로 캐싱이 중요하고, curl로 바로 테스트 가능해야 한다. 내부 API는 우리 프론트엔드가 주로 사용하므로 타입 안전성과 개발 효율이 더 중요하다. 두 가지를 병행함으로써 각각의 장점을 취할 수 있다.
버전 관리와 에러 처리
REST에서는 URL 경로에 버전을 명시하는 방식이 가장 명확하다. /api/v1/, /api/v2/ 이런 식이다. 3-6개월마다 새 버전을 출시하고, 구 버전은 12개월 뒤 종료하는 정책이 일반적이다. GraphQL은 버전 숫자가 필요 없다. 필드를 추가하고 deprecated 마크를 하면 된다. 에러 처리는 REST가 HTTP 상태 코드를 활용하고, GraphQL은 항상 200으로 응답하고 errors 필드에 상세 정보를 담는다. 두 방식 모두 명확한 에러 코드와 메시지, 추적용 request ID를 포함하는 게 중요하다.
결론
REST vs GraphQL은 "어느 것이 더 나은가"가 아니라 "언제 어디에 쓸 것인가"의 문제다. 우리는 둘 다 쓰고 있고, 이게 최고의 선택이었다.