크로키의 스택 - REST API

카카오스타일(크로키닷컴)이 2012년부터 REST API를 기본으로 사용하면서 실제 서비스를 만들다 마주친 REST의 한계 사례를 정리한 글이다. 교과서적 REST와 실무 API 설계의 간극을 솔직하게 드러내고, 최종적으로 GraphQL 전환을 검토하게 된 배경까지 이어진다.

핵심 포인트 - REST API는 HTTP 동사·리소스 URI 명명 관습이지만, Roy Fielding의 원 REST 아키텍처와는 다름 (HATEOAS, stateless 미적용) - 로그인/로그아웃 같은 동사성 액션은 REST URL로 표현하기 어려워 non-REST 스타일 혼용 - 여러 리소스를 한 번에 가져오거나 필드를 선택적으로 요청하는 경우 REST URL 설계가 번거로움 - 같은 리소스 URI지만 쿼리 인자에 따라 처리 코드가 다른 경우 REST 명명이 어색함 - 현실 결론: REST를 기본으로 하되, 맞지 않는 케이스는 RPC 스타일(/getProductPrices 등) 혼용 - 마이크로서비스 간에는 Thrift 도입, 클라이언트-서버도 통일하기 위해 GraphQL 탐색 중

상세 정리 - 쿠키 사용(stateless 위반), HATEOAS 미구현, Accept 헤더 미인식 등 현실적 타협 설명 - 로그인 처리 딜레마: /users/me/login 은 동사, POST /sessions 는 어색함 → non-REST API로 별도 처리 - non-REST API 실제 사례: /login, /acceptJoinRequest, /ignoreJoinRequest, /joinMatch, /linkWithFacebook - 여러 리소스 한 번에: GET /events/123?add=attendances,place 처럼 add 인자로 처리 - 배열 조회: GET /products/1,6,29,35/price 는 URL 길이 제한에 걸릴 위험 → /getProductPrices RPC 스타일 - 필드 선택: fields 인자로 추가 DB 접근이 필요한 필드만 선택 요청하는 규칙 - 같은 /products 라우트지만 검색어 검색·카테고리 검색 처리 코드가 다른 어색함 - /resources/valid, /resources/my-query 같은 상태·검색 URI 명명의 어려움 (GitHub 사례 언급) - 현재 상태: REST 기본 + 마이크로서비스 간 Thrift + 클라이언트-서버 GraphQL 실험 중

왜 읽나: REST API를 교과서대로 설계하다 현실 요구사항에 맞지 않는 경우를 반복해서 겪은 개발자라면, 비슷한 고민의 실전 사례와 프로젝트가 실제로 어떤 판단을 내렸는지 확인할 수 있다.