ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-116] QUERY ​

概述 ​

HTTP QUERY 方法定義於 RFC 10008，是一個安全且冪等的請求方法，可攜帶請求主體來描述目標資源應如何處理這個請求。它填補了 GET(無法攜帶請求主體)與 POST(既不安全也不保證冪等)之間的空隙——讓複雜的查詢可以透過請求主體表達，同時保留 GET 的安全性與可快取特性。

指導原則 ​

  • QUERY 請求必須(MUST)被視為安全：客戶端不要求也不期望目標資源的狀態發生任何變化。
  • QUERY 請求必須(MUST)被視為冪等，可以(MAY)在需要時自動重試或重複發送，例如連線失敗之後。
  • QUERY 是安全且冪等的，跟存取控制無關；端點仍必須(MUST)獨立實施身份驗證與授權。參見 ADP-123: Authorization。
  • 請求主體必須(MUST)包含描述查詢內容的表示法(representation)；Content-Type 標頭必須(MUST)指出該表示法的媒體類型。
  • 若請求缺少媒體類型資訊，伺服器必須(MUST)以 4xx 狀態碼讓請求失敗，通常為 400 Bad Request。
  • 若請求指定了伺服器不支援的媒體類型，伺服器應該(SHOULD)回應 415 Unsupported Media Type。
  • 若媒體類型受支援且內容格式正確，但查詢因其實際內容而無法處理(例如語法正確卻參照到不存在的欄位)，伺服器應該(SHOULD)回應 422 Unprocessable Content。
  • 若客戶端透過 Accept 要求伺服器不支援的回應媒體類型，伺服器應該(SHOULD)回應 406 Not Acceptable。
  • QUERY 的錯誤回應(400/415/422/406)必須(MUST)遵循 HTTP Problem Details 格式。參見 ADP-401: HTTP Problem Basics。
  • 成功的回應(2xx)可以(MAY)包含 Content-Location 標頭，指向對應查詢結果的資源，讓客戶端之後能以一般的 GET 取回相同結果。若查詢內容含有敏感資訊，伺服器不可(MUST NOT)把任何敏感部分編進這個 Content-Location URI（RFC 10008 §4）——因為 URI 被記錄(log)的範圍遠比請求主體廣泛。
  • 對 QUERY 請求的回應應該(SHOULD)是可快取的。由於查詢內容表達在請求主體而非 URI 中，快取金鑰必須(MUST)納入請求內容與相關中繼資料。參見 ADP-361: HTTP 快取。
  • 資源應該(SHOULD)使用 Accept-Query 回應標頭來宣告支援 QUERY 方法，以及可接受的查詢媒體類型，詳見下方說明。
  • 只有在查詢複雜度超出查詢字串合理承載範圍時，才應該(SHOULD)優先使用 QUERY，而非 POST /resources/search 這類自訂端點。預設做法請參見 ADP-311: 過濾 與 ADP-318: 查詢參數慣例。

Accept-Query 標頭 ​

資源可以(MAY)使用 Accept-Query 回應標頭來宣告支援 QUERY 方法，並識別可接受的查詢媒體類型：

http
Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

範例 ​

請求:

http
QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10

回應:

http
HTTP/1.1 200 OK
Content-Type: application/json

[
  { "surname": "Smith", "givenname": "John", "email": "smith@example.org" },
  { "surname": "Jones", "givenname": "Sally", "email": "sally.jones@example.com" }
]

採用檢查清單 ​

在正式環境採用 QUERY 之前，請逐項確認以下項目——截至 2026-07，整個生態系的支援程度並不一致：

  • 客戶端：現代 fetch/XMLHttpRequest 支援任意方法字串，但 QUERY 不在 CORS 的安全清單(safelisted methods)內，跨來源請求必須(MUST)正確處理標準的 OPTIONS 預檢請求。
  • 伺服器執行環境：確認你的 HTTP 伺服器/解析器能正確識別 QUERY 為合法的方法字串，而不是直接拒絕連線。
  • 中間層/body 完整性：假設 safe method 不會帶 body 的 proxy、load balancer、WAF，可能會把 QUERY 的 request body 截斷、緩衝處理錯誤或造成前後不同步——導致悄悄產生錯誤結果，或形成 request smuggling 的攻擊面。務必確認請求路徑上的每一個節點都會完整轉發 QUERY 的 body。
  • 邊緣/CDN：部分 CDN 服務對 HTTP method 採用固定的允許清單，可能會直接拒絕清單外的方法；使用前請先確認邊緣層文件記載的允許方法設定。
  • API 閘道：部分受管理的 API 閘道要求每個支援的 method 都要在路由上明確宣告，其宣告語法可能尚未認得 QUERY；使用前請確認你的閘道是否直接支援，或是否需要改用萬用/proxy 路由。
  • 共享快取：確認 API 前面的共享/反向快取能將請求主體內容納入快取金鑰；否則 QUERY 的可快取優勢無法成立。
  • OpenAPI 工具鏈：query 作為一級 operation 是在 OpenAPI Specification 3.2 才新增的；在 OpenAPI 文件中記載 QUERY 端點前，請先確認你使用的規格版本與工具鏈(驗證器、程式碼產生器、文件渲染器)是否已支援。

參考 ​

Changelog ​

  • 2026.07.08 初版。