검색 API, GET이냐 POST냐 그만 싸우자: 새 HTTP QUERY 메서드 정리

검색 API를 만들어 본 적 있다면 한 번쯤 이 고민을 했을 거예요. '검색 조건을 GET으로 보내야 하나, POST로 보내야 하나?'

GET으로 보내자니 조건이 복잡해지면 URL이 끝도 없이 길어지고, 한글이나 특수문자를 인코딩하다 보면 주소창이 외계어가 돼요. 게다가 URL은 길이 제한도 있어서 조건이 많으면 잘려나가기도 하죠. 그렇다고 POST로 보내자니 이건 원래 '데이터를 새로 만든다'는 의미라 검색이라는 행동이랑 안 맞아요. 캐싱(한 번 받은 결과를 저장해 두고 재사용하는 것)도 잘 안 되고요.

이 오래된 딜레마를 풀기 위해 등장한 게 바로 새로운 HTTP 메서드 QUERY예요.

QUERY가 뭐가 다른가요

지금까지 우리가 쓰던 메서드는 GET, POST, PUT, DELETE 정도였죠. QUERY는 여기에 새로 추가되는 메서드인데, 한마디로 '본문(body)을 가질 수 있는 GET'이에요.

이게 왜 중요하냐면, HTTP 메서드에는 두 가지 중요한 성질이 있어요. 하나는 safe(안전함) — 서버 데이터를 바꾸지 않는다는 뜻이고, 다른 하나는 idempotent(멱등성) — 같은 요청을 몇 번 보내도 결과가 똑같다는 뜻이에요. GET은 이 두 성질을 다 가지고 있어서 캐싱도 되고 안심하고 재시도할 수 있죠. 문제는 GET은 본문을 제대로 쓸 수 없다는 거였어요.

QUERY는 GET처럼 safe하고 idempotent하면서도, 본문에 검색 조건을 자유롭게 담을 수 있어요. 본문 형식도 Content-Type 헤더로 마음대로 정할 수 있어서, JSON으로 보내든 GraphQL 쿼리를 담든 SQL 비슷한 걸 넣든 자유예요. URL 길이 걱정 없이 복잡한 조건을 깔끔하게 보낼 수 있는 거죠.

응답에는 Content-Location 헤더를 붙여서 '이 검색 결과는 이 주소에서도 볼 수 있어요'라고 알려줄 수 있어요. 덕분에 캐싱도 GET처럼 제대로 동작합니다.

사실 비슷한 시도가 있었어요

이게 완전히 새로운 발상은 아니에요. 예전 WebDAV에는 SEARCH라는 메서드가 있었거든요. 하지만 너무 WebDAV 전용이라 일반 웹 API로는 거의 안 쓰였죠. 또 Elasticsearch 같은 검색엔진은 예전부터 'GET에 body를 넣는' 비표준 방식을 써왔는데, 표준이 아니다 보니 중간의 프록시나 라이브러리가 body를 그냥 버리는 사고가 종종 났어요.

QUERY는 이런 어정쩡한 관행들을 정식 표준으로 깔끔하게 정리하는 셈이에요. GraphQL이 모든 걸 POST로 처리하면서 캐싱을 포기했던 것과 비교해도, QUERY는 캐싱을 살릴 수 있다는 점에서 매력적이고요.

한국 개발자에게는

아직 IETF(인터넷 표준을 만드는 단체)의 표준 초안 단계라, 당장 모든 브라우저와 서버가 지원하는 건 아니에요. 그래서 실무에 바로 쓰기엔 이르지만, 방향성은 알아둘 가치가 충분해요.

특히 복잡한 검색·필터 API를 설계하는 분이라면, '왜 우리가 그동안 GET이냐 POST냐로 싸웠는지', 그리고 그 해법이 어떻게 표준화되는지 이해하면 API 설계 감각이 한 단계 올라가거든요. 나중에 프레임워크들이 QUERY를 지원하기 시작하면, 미리 알고 있던 사람이 가장 먼저 깔끔한 설계를 가져갈 수 있어요.