HTTP QUERY 메서드(RFC 10008): 복잡한 검색을 GET과 POST 대신 보내는 방법
복잡한 검색을 GET으로 보내면 URL 길이와 로그 노출에 막히고, POST로 도망치면 safe·idempotent·cacheable을 잃는다. RFC 10008의 QUERY 메서드가 이 오래된 타협을 어떻게 끝내는지 정리한 글이다.
복잡한 검색 API는 GET과 POST 중 하나를 골라야 했다.
- GET은 의미상 맞다. 검색은 서버 상태를 바꾸지 않는 읽기 동작이다. 하지만 필터, 정렬, 중첩 조건, 좌표 배열을 쿼리스트링에 넣으면 URL이 수 KB를 넘고, 프록시나 서버가 요청을 거부한다.
- POST는 바디에 JSON으로 조건을 담아 길이 문제를 피한다. 대신 이 요청이 읽기 전용이라는 의미가 사라진다.
HTTP에는 바디를 가지면서 읽기 전용임이 보장되는 메서드가 없었다. RFC 10008의 QUERY가 이 메서드다.
GET의 한계
URL 길이 제한 RFC는 URI 길이 상한을 정하지 않지만, 서버·프록시·CDN은 대개 8KB 안팎에서 요청 라인을 거부한다. 검색 조건이 사용자 입력으로 늘어나면 실제 장애가 된다.
로그에 남는 민감한 조건 쿼리스트링은 액세스 로그, 프록시 로그, 브라우저 히스토리, Referer 헤더에 그대로 남는다. 검색 조건에 이메일·전화번호·내부 식별자가 있으면 모두 평문으로 퍼진다.
바디 사용 불가 GET에 바디를 싣는 것이 금지된 것은 아니지만, 중간 장비들이 GET 바디를 무시하거나 버려서 실제로는 쓸 수 없다. GET은 주소만으로 자원을 가리키는 메서드라 바디를 위한 자리가 없다.
POST로 보낼 때 잃는 것
POST는 바디를 자유롭게 쓸 수 있어서 대부분의 검색 API가 POST /search 형태가 됐다. 하지만 POST는 “이 요청이 서버 상태를 바꿀 수 있다”는 의미의 메서드다.
재시도 불가 응답을 받지 못했을 때 POST는 다시 보내도 되는지 메서드 의미만으로 판단할 수 없다. 검색 요청이어도 클라이언트는 재시도를 보수적으로 처리해야 한다.
캐시 불가 POST 응답은 기본적으로 캐시되지 않는다. 같은 검색을 반복해도 매번 오리진까지 가서 다시 계산하고, CDN이나 리버스 프록시 캐시를 쓰지 못한다.
| GET | POST | QUERY | |
|---|---|---|---|
| 요청 바디 | ✗ | ✓ | ✓ |
| safe (상태 안 바꿈) | ✓ | ✗ | ✓ |
| idempotent (재시도 안전) | ✓ | ✗ | ✓ |
| 캐시 가능 | ✓ | ✗ | ✓ |
QUERY 메서드
RFC 10008이 정의하는 QUERY는 바디를 가질 수 있는 GET이다. 명세가 보장하는 성질은 두 가지다.
- safe: 대상 자원의 상태를 바꾸지 않는다.
- idempotent: 자동으로 재시도하거나 다시 시작해도 안전하다.
클라이언트와 중간 장비는 메서드 이름만 보고 읽기 전용이며 재전송해도 된다고 판단할 수 있다.
1
2
3
4
5
6
7
8
9
10
QUERY /products HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json
{
"filter": { "category": "laptop", "priceMax": 1500000 },
"sort": [{ "field": "price", "order": "asc" }],
"page": { "size": 20 }
}
Content-Type은 필수다. 서버가 바디를 해석해야 하므로 타입 없는 QUERY는 4xx로 거부되고, 서버가 모르는 포맷이면 415 Unsupported Media Type으로 응답한다.
명세에 함께 정의된 것
Accept-Query응답 헤더 서버가 해당 자원에서 QUERY를 지원하고 어떤 미디어 타입을 받는지 알리는 헤더다. Structured Fields 문법으로 지원 포맷을 나열한다. 클라이언트는 QUERY를 보내기 전에 지원 여부를 확인할 수 있다.바디를 포함하는 캐시 키 QUERY 응답은 캐시할 수 있다. 캐시 키에는 URL뿐 아니라 요청 바디(content)와 관련 메타데이터가 포함돼야 한다. 같은 URL이라도 검색 조건이 다르면 응답이 달라야 하기 때문이다.
결과를 가리키는 방법
303 See Other: 결과를 별도 자원으로 돌려보내는 간접 응답Content-Location: 이 쿼리 결과를 가져올 수 있는 URILocation: 같은 쿼리를 GET으로 반복할 수 있는 URI
Location을 쓰면 무거운 검색을 QUERY로 한 번 실행한 뒤, 서버가 돌려준 URL로 이후에는 일반 GET과 캐시를 사용할 수 있다.
바디 기반 캐시 키의 구현 문제
리버스 프록시, CDN, 브라우저 캐시는 “메서드 + URL”을 키로 동작하도록 설계돼 있다. 바디를 키에 넣으려면 캐시 계층이 요청 본문을 읽고 정규화해서 해시를 만들어야 하는데, 기존 캐시 미들웨어는 이 기능을 기본으로 제공하지 않는다. QUERY의 캐시 이점은 명세만으로 생기지 않고, 캐시 인프라가 바디 기반 키를 구현해야 실제로 생긴다.
도입 전망
RFC 10008 공동 저자는 Julian Reschke(greenbytes), James M. Snell(Cloudflare), Mike Bishop(Akamai)이다. 셋 중 둘이 대형 CDN 소속이고, 바디 기반 캐시 키를 구현할 동기가 가장 큰 쪽도 CDN이다. 예상되는 전파 순서는 다음과 같다.
- CDN·엣지:
Accept-Query와 바디 기반 캐시 구현 - HTTP 클라이언트·서버 라이브러리: curl, 각 언어 HTTP 스택이 메서드 허용
- 애플리케이션 프레임워크: 라우팅 DSL에
QUERY매핑 추가
Accept-Query 덕분에 기존 인터넷을 깨지 않고 도입할 수 있다. 서버가 QUERY 지원을 알릴 때만 클라이언트가 QUERY를 쓰고, 그렇지 않으면 기존 GET·POST로 폴백한다.
당장 모든 검색 API를 QUERY로 바꿀 필요는 없다. 지금 POST /search를 설계한다면, 그 POST는 검색에 맞는 메서드여서가 아니라 대안이 없어서 고른 것이라는 점을 알고 쓰면 된다.
정리
- 메서드의 의미(safe·idempotent)는 문서상의 설명이 아니라 캐시와 재시도 같은 인프라가 실제로 사용하는 계약이다.
- POST 검색은 이 계약을 비워둔 요청이다.
- QUERY는 검색이 읽기 동작이라는 점을 메서드 수준에서 표현해서, 캐시와 재시도를 다시 쓸 수 있게 한다.