HTTP QUERY Method Explained: RFC 10008, Ecosystem Adoption, and a Quarkus Implementation

왜 HTTP QUERY 메서드가 필요한가

검색 API를 설계하다 보면 GET 방식의 한계에 부딪히는 순간이 온다. 단순한 검색 조건이라면 쿼리 파라미터로 충분하지만, 필터가 중첩되고 조건이 복잡해질수록 URI 길이 제한이 현실적인 장벽이 된다. 브라우저와 서버마다 다르지만 일반적으로 URI는 2,000~8,000자 내외로 제한되며, 이를 초과하면 요청 자체가 실패한다.

보안 측면의 문제도 크다. URI에 민감한 검색 조건을 담으면 해당 값이 웹 서버 접근 로그, 브라우저 히스토리, 프록시 서버, 모니터링 시스템 등 여러 레이어에 그대로 노출된다. 개인 식별 정보나 비즈니스 크리티컬한 필터 조건이 포함된 쿼리라면 이는 무시할 수 없는 보안 리스크다.

GET with Body는 왜 해결책이 아닌가

GET 요청에 바디를 포함하는 방식은 HTTP 스펙이 명시적으로 금지하지는 않지만, 정의되지 않은 동작(undefined behavior)이다. Elasticsearch의 검색 API가 대표적인 사례인데, Elastic 자사 공식 문서에서도 이 문제를 직접 인정하고 있다.

"일부 HTTP 서버는 이를 허용하지만, 특히 캐싱 프록시는 허용하지 않을 수 있다. [...] GET with body가 보편적으로 지원되지 않기 때문에, 검색 API는 POST 요청도 함께 지원한다."

결국 Elasticsearch조차 POST를 대안으로 제공해야 했다. 그런데 POST를 사용하면 멱등성(idempotency) 의미론이 깨진다. 캐싱 프록시와 CDN은 POST 요청을 기본적으로 캐시하지 않으며, API 게이트웨이 레이어에서의 캐시 전략 수립도 어려워진다. 읽기 전용 검색 작업임에도 불구하고 POST를 쓰는 것은 의미론적으로 부정확한 타협이다.

RFC 10008: QUERY 메서드의 설계 원칙

HTTP QUERY 메서드는 이 딜레마를 해결하기 위해 RFC 10008로 표준화가 진행 중이다. 핵심 설계 원칙은 두 가지다. GET과 동일하게 읽기 전용·멱등성을 보장하면서, POST처럼 요청 바디에 복잡한 검색 조건을 담을 수 있다.

QUERY /products HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "filters": {
    "category": "electronics",
    "price": { "min": 10000, "max": 500000 },
    "tags": ["sale", "new"]
  },
  "sort": { "field": "price", "order": "asc" }
}

멱등성이 보장된다는 것은 프록시와 CDN이 QUERY 요청을 GET처럼 캐시 가능한 요청으로 처리할 수 있다는 의미다. 대규모 검색 API에서 동일한 복잡한 조건의 반복 조회를 캐시 레이어에서 처리할 수 있게 되어, 백엔드 부하를 실질적으로 줄일 수 있는 구조적 이점이 생긴다.

실무 도입 시 고려사항

현재 Quarkus 등 일부 프레임워크에서 QUERY 메서드 구현 사례가 나오고 있지만, 생태계 전반의 채택은 아직 초기 단계다. 프로덕션 환경에 도입하기 전 반드시 점검해야 할 항목들이 있다.

미들웨어 호환성: API 게이트웨이(Kong, AWS API Gateway 등), 로드밸런서, 리버스 프록시가 QUERY 메서드를 허용 메서드로 인식하는지 확인 필요
클라이언트 라이브러리: 브라우저 fetch API, axios, OkHttp 등 주요 HTTP 클라이언트의 지원 여부 검토
보안 정책: WAF(Web Application Firewall) 규칙이 알 수 없는 메서드를 차단하는 경우 예외 처리 필요
모니터링·로깅: APM 도구와 로그 수집 파이프라인이 QUERY 메서드를 올바르게 파싱하는지 확인

RFC가 최종 확정되기 전까지는 신규 서비스의 내부 API나 실험적 엔드포인트에 제한적으로 적용하면서 호환성을 검증하는 방식이 현실적이다.

정리

HTTP QUERY 메서드는 GET의 URI 길이·보안 한계와 POST의 의미론적 부정확함을 동시에 해결하는 RFC 10008 표준화 진행 중인 메서드다
멱등성을 보장하면서 요청 바디를 허용하므로, 복잡한 검색 API에서 캐시 전략과 의미론적 정확성을 함께 확보할 수 있다
생태계 채택이 초기 단계인 만큼, 프로덕션 도입 전 API 게이트웨이·WAF·클라이언트 라이브러리 등 미들웨어 호환성 검토가 필수다