REST API 설계의 오랜 공백: 복잡한 검색 요청을 어떻게 표현할 것인가
REST API를 설계하다 보면 반드시 마주치는 상황이 있다. 복잡한 검색 조건을 서버에 전달해야 하는 경우다. 예를 들어 여러 필터 조건, 중첩된 쿼리 구조, 또는 민감한 파라미터를 포함한 검색 요청을 처리해야 할 때 현행 HTTP 메서드만으로는 명확한 의도 표현에 한계가 생긴다.
GET은 리소스 조회를 의미하지만 요청 본문(body)을 공식적으로 지원하지 않는다. 복잡한 검색 조건을 쿼리스트링으로만 표현하면 URL 길이 제한에 부딪히고, 구조화된 JSON 페이로드를 담기도 어렵다. 그렇다고 POST를 쓰자니 의미가 맞지 않는다. POST는 "새로운 리소스를 생성한다"는 의도를 내포하기 때문에, 검색 요청에 POST를 사용하면 클라이언트와 서버 사이의 의미 계약이 흐려진다.
현장에서 자주 쓰이는 타협안과 그 한계
실무에서는 이 문제를 다양한 방식으로 우회해왔다.
- GET + 쿼리스트링: 단순한 필터에는 유효하지만, 조건이 복잡해질수록 URL이 길어지고 인코딩 문제가 생긴다.
- POST /search: 의미론적으로 부정확하다. 캐싱, 멱등성 보장이 안 되며 중간 프록시나 CDN이 오해할 수 있다.
- POST로 임시 쿼리 리소스 생성 후 GET: 두 번의 왕복 요청이 필요해 불필요한 복잡도가 추가된다.
// 흔히 쓰이는 우회 방식 - POST로 검색을 표현
@PostMapping("/users/search")
public List<User> searchUsers(@RequestBody UserSearchRequest request) {
// POST이지만 실제로는 조회만 수행
return userService.search(request);
}
이 방식은 동작은 하지만 HTTP 명세의 의미론적 계약을 위반한다. 멱등성이 보장되어야 할 검색 요청이 POST로 표현되면, 네트워크 오류 시 재시도 로직을 안전하게 구현하기 어려워지고, 캐싱 레이어도 정상적으로 동작하지 않는다.
HTTP QUERY 메서드: 간극을 메우는 새로운 표준
이 문제를 해결하기 위해 IETF에서는 HTTP QUERY 메서드를 표준화하는 작업을 진행해왔다. QUERY는 GET처럼 리소스를 조회하는 의도를 가지되, POST처럼 요청 본문에 구조화된 데이터를 담을 수 있도록 설계되었다. 즉, 멱등성과 안전성(safety)을 유지하면서 복잡한 검색 페이로드를 전달하는 것이 핵심이다.
Java 백엔드 관점에서 보면, Spring MVC나 JAX-RS 같은 프레임워크가 QUERY 메서드를 지원하게 될 경우 아래와 같은 방식으로 명확하게 의도를 표현할 수 있게 된다.
// QUERY 메서드를 활용한 의미론적으로 올바른 검색 표현 (개념 예시)
@QueryMapping("/users")
public List<User> queryUsers(@RequestBody UserSearchRequest request) {
// 멱등성 보장, 본문 포함 가능, 조회 의도 명확
return userService.search(request);
}
현시점에서 Java 생태계의 프레임워크 지원은 아직 성숙 단계에 이르지 않았지만, API 설계 원칙 차원에서 QUERY 메서드의 등장 배경과 의도를 이해하는 것은 중요하다. 복잡한 검색 API를 설계할 때 "왜 POST를 쓰면 안 되는가"에 대한 명확한 근거를 갖추게 되기 때문이다.
정리
- GET의 URL 길이 한계와 POST의 의미론적 부정확함 사이의 공백을 메우기 위해 HTTP QUERY 메서드가 등장했다.
- QUERY는 요청 본문을 허용하면서도 멱등성과 조회 의도를 명확히 표현할 수 있어, 복잡한 REST 검색 API 설계에 적합하다.
- Java 백엔드 개발자라면 프레임워크 지원 성숙도를 모니터링하면서, 현재 설계 결정에 이 표준이 미칠 영향을 미리 고려해두는 것이 좋다.