[ADP-318] 查詢參數慣例

指導原則

應該(SHOULD)在 GET 請求中使用查詢參數
可以(MAY)在 POST 請求中使用查詢參數
TIP
這是一個慣例，而不是一個硬性的規則。如需進一步的討論，請參考這裡和這裡。
在我看來，在POST請求中同時使用payload和查詢參數可能會導致輸入碎片化。從另一個角度看，保持使用payload的一致性意味著你需要將通用的查詢參數移到payload中，並且可能需要為它們設計一個新的屬性/值配對。
應該(SHOULD)在 POST 請求中使用負載（請求主體）
應該(SHOULD)遵循常見的查詢參數
- DRAFT q
- sort：參見排序
- filter：參見過濾
- fields：參見部分回應
- embed：參見資源擴展
- offset：參見分頁
- cursor：參見分頁

必須(MUST)使用 camelCase 在連結字作為查詢參數時

正確:

raw

productId, articleNumber, loginId, lId etc.

錯誤:

raw

product_id, Articlenumber, login-id, LID

正確做法

http

GET /events?occuredAt=2024-07-09T18:00:00Z
POST /search
{
  "occuredAt": "2024-07-09T18:00:00Z"
}

錯誤做法

http

POST /search?occuredAt=2024-07-09T18:00:00Z
GET /events
{
  "occuredAt": "2024-07-09T18:00:00Z"
}