Proxyman이 이제 HTTP QUERY 메서드를 지원합니다

API는 데이터를 검색하거나 필터링해야 하는 경우가 많습니다. 간단한 검색이라면 보통 GET 요청으로 충분합니다. 하지만 필터가 많은 검색에서는 URL이 길어져 읽고 관리하기 어려워집니다.

이제 QUERY라는 새로운 HTTP 메서드가 등장했습니다. API에 “데이터를 찾아 주세요. 단, 아무것도 변경하지 마세요.”라고 명확하게 전달할 수 있는 방법입니다.

이제 Proxyman은 앱 전반에서 QUERY 요청을 지원합니다. 직접 작성하고, 캡처된 트래픽에서 확인하고, 많은 목록 속에서 필터링하고, 평소 사용하는 디버깅 도구와 함께 활용할 수 있습니다.

1. HTTP QUERY 메서드란?

QUERY는 서버에 데이터 검색, 필터링, 선택을 요청하기 위한 새로운 HTTP 메서드입니다. 쿼리 세부 정보는 URL 대신 요청 본문에 담겨 전송됩니다.

핵심은 간단합니다. QUERY 요청은 데이터를 읽기 위한 것입니다. 무언가를 생성, 수정, 삭제해서는 안 되며, 필요하면 다시 보내도 안전합니다.

이 메서드는 RFC 10008에 정의되어 있습니다. 다른 HTTP 메서드와 마찬가지로, API 서버가 지원하도록 설정한 경우에만 동작합니다.

GET 및 POST와 무엇이 다른가요?

GET, QUERY, POST 모두 API에 입력값을 보낼 수 있습니다. 차이는 입력값이 어디에 담기는지, 그리고 메서드가 요청에 대해 무엇을 말해 주는지에 있습니다.

GET은 검색 값을 URL에 담습니다. 북마크하거나 공유하고 싶을 수 있는 간단한 요청에 적합합니다: /products?brand=Proxyman&sort=price.
QUERY는 검색 값을 요청 본문에 담습니다. 필터가 많은 상세 검색에 적합하며, 서버에 이 요청이 읽기 전용임을 알려 줍니다.
POST도 요청 본문에 데이터를 담아 보냅니다. 주문 제출처럼 무언가를 생성하거나 변경하는 데 자주 쓰입니다. API가 검색에 POST를 사용할 수도 있지만, 메서드 자체만으로는 데이터를 변경하는지 알 수 없습니다.

요약하면, URL 기반의 간단한 조회에는 GET, 상세한 읽기 전용 검색에는 QUERY, 작업이 데이터를 생성하거나 변경할 수 있을 때는 POST를 사용하세요.

간단한 cURL 예제

상세한 필터 조건으로 상품을 검색할 수 있는 온라인 스토어를 떠올려 보세요. 다음 요청은 가격순으로 정렬된 재고 있는 무선 헤드폰을 요청합니다:

curl --request QUERY 'https://api.example.com/products/search' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "text": "wireless headphones",
    "filters": {
      "inStock": true
    },
    "sort": "price"
  }'

--request QUERY 부분이 HTTP 메서드를 지정합니다. 그 아래의 JSON은 검색 입력값이며, Content-Type은 서버에 이 데이터가 JSON임을 알려 줍니다.

GET을 사용한다면 같은 검색 조건을 URL에 모두 담아야 합니다. 필드가 많을 때는 이 방식이 불편할 수 있습니다.

아직 모든 API가 QUERY를 받아들이는 것은 아닙니다. 서버가 지원하지 않으면 405 Method Not Allowed가 표시될 수 있습니다. 이 응답은 Proxyman이 아니라 API 서버에서 온 것입니다.

2. Proxyman에서 QUERY 요청 작성하기

이제 Compose 도구에서 바로 QUERY 요청을 보낼 수 있습니다. 새로운 엔드포인트를 시험하거나, 응답을 확인하거나, 결과를 GET 또는 POST 요청과 비교하고 싶을 때 유용합니다.

Proxyman에서 Compose를 엽니다.
메서드 메뉴에서 QUERY를 선택합니다.
API URL을 입력합니다.
API에 필요한 헤더를 추가합니다. JSON 요청이라면 보통 Content-Type: application/json입니다.
Body 탭에 검색 입력값을 입력합니다.
Send를 클릭하고 오른쪽에서 응답을 확인합니다.

스크린샷은 405 Method Not Allowed 응답을 보여 줍니다. 이는 Proxyman이 QUERY를 보냈지만 선택한 엔드포인트가 이를 지원하지 않는다는 것을 확인해 줍니다. 성공 응답을 받고 싶다면 QUERY 지원을 문서화한 엔드포인트를 사용하세요.

3. QUERY 트래픽 빠르게 찾기

앱이 QUERY를 사용하기 시작하면 수많은 GET 및 POST 요청 사이에서 놓치기 쉽습니다. Proxyman은 Method 열에 QUERY를 표시하므로 한눈에 식별할 수 있습니다.

QUERY만 보려면 필터 바를 열고 Method를 QUERY로 설정하세요. 그러면 Proxyman은 조건에 맞는 요청만 표시하여 검사하거나 비교할 수 있게 합니다.

검색 화면을 테스트할 때 특히 유용합니다. 값을 바꾸고 검색을 다시 실행한 뒤, 관련 없는 트래픽을 뒤지지 않고 해당 요청을 바로 확인할 수 있습니다.

4. 익숙한 디버깅 도구와 QUERY 함께 사용하기

QUERY는 Compose와 필터에만 국한되지 않습니다. Proxyman은 요청 메서드가 중요한 곳이라면 어디에서든 이를 인식하므로, 평소의 디버깅 워크플로에 자연스럽게 들어맞습니다.

요청 세부 정보: 캡처된 요청에서 QUERY를 확인하고, 다른 메서드와 마찬가지로 헤더, 쿼리 값, 본문, 응답을 읽을 수 있습니다.
Debugging Tools: 도구에서 메서드로 요청을 매칭할 수 있다면 QUERY를 선택해 규칙이 해당 검색에만 적용되도록 하세요. GET 및 POST 트래픽은 그대로 둘 수 있습니다.
Scripting: QUERY 요청에만 스크립트를 실행하세요. 로컬 테스트 중 검색 입력값을 확인하거나, 테스트용 헤더를 추가하거나, 응답을 변경하고 싶을 때 유용합니다.
Breakpoint: QUERY 요청이 서버에 도달하기 전에 일시 중지하세요. 검색 입력값을 검토하거나 수정한 뒤 요청을 보내고 결과를 검사할 수 있습니다.

이러한 기능을 사용하면 규칙이나 스크립트가 테스트하려는 요청만 정확히 대상으로 삼고, 업데이트나 결제 요청에는 영향을 주지 않습니다.

5. 요약 및 다음 단계

HTTP QUERY 메서드는 API의 의도를 더 분명하게 만듭니다. 데이터를 변경하지 않고 데이터를 요청하는 것입니다. 검색 조건이 짧은 URL에 편하게 담기 어려울 만큼 상세할 때 유용합니다.

이제 Proxyman으로 다음 작업을 할 수 있습니다:

QUERY 요청 작성 및 전송
QUERY 트래픽 캡처 및 검사
메인 목록을 QUERY 메서드로 필터링
Debugging Tools, Scripting, Breakpoint에서 QUERY 요청을 대상으로 지정

새로운 HTTP 메서드를 지원하는 데는 시간이 걸립니다. 앱에서 사용하기 전에 API 문서를 확인하거나 엔드포인트를 먼저 시험해 보세요. 405 Method Not Allowed가 반환된다면 아직 QUERY를 지원하지 않는 것입니다.

서버만이 아니라 앱에서 서버까지 전체 경로를 테스트하세요. 오래된 게이트웨이, 방화벽, 또는 클라이언트 라이브러리는 알지 못하는 메서드를 거부할 수 있습니다. 또한 자체 시스템의 재시도 및 캐시 동작도 확인하세요. 이 메서드는 요청이 읽기 전용임을 나타내지만, 경로의 각 구성 요소가 이를 올바르게 처리해야 합니다.

Proxyman을 최신 상태로 유지하면 더 많은 API가 QUERY를 도입하더라도 해당 트래픽을 검사하고 디버깅할 준비가 됩니다. 더 알아보려면 RFC 10008을 읽거나 Proxyman 문서를 방문하세요.