[ADP-317] JSON 回應

指導原則

• 應該(SHOULD)使用 JSON 作為頂層回應格式。

  TIP

  為了明確起見，建議避免(SHOULD NOT)使用陣列作為頂層回應。 這種方法在未來需要將元數據注入到 JSON 物件中時提供了靈活性，例如超媒體連結。此外，使用陣列作為頂層回應有安全隱患，請見參考連結。

• 在 GET 方法的集合結果中，應該(SHOULD)使用駝峰式命名的集合名稱作為屬性。

• 在使用 POST 方法的基於動作的請求中，應該(SHOULD)使用駝峰式命名的動作名稱作為屬性。

  POST /search HTTP/1.1
  
  HTTP/1.1 200 OK
  {
    search: [],
  }
  
  POST /users/batch HTTP/1.1
  
  HTTP/1.1 200 OK
  {
    batch: [],
  }

• 如果路徑的最後一段是資源集合的修飾詞，應該使用駝峰式命名的集合名稱。

  GET /products/most-popular HTTP/1.1
  
  HTTP/1.1 200 OK
  {
    products: []
  }

設計思考

這條規則是為 JSON 回應中的元數據設計的。在陣列中放置元數據是困難的。

棘手的部分出現在對 GET 請求的集合回應中。

由於我們定義:

• URI 中的集合應使用短橫線命名法。
• 屬性名稱應使用駝峰式命名法。

我們在返回複數結果時，將集合名稱的短橫線命名法轉換為駝峰式命名法。

為了與上述規則保持一致，在基於動作的請求情況下使用動作作為屬性名稱。

然而，對於修飾詞的情況，主體仍然是集合，所以我們應該仍然返回集合。

示例

正確做法

GET /planets HTTP/1.1

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

{
  planets: []
}

---

GET /dwarf-planets HTTP/1.1

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

{
  dwarfPlanets: []
}

錯誤做法

GET /universes HTTP/1.1

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

[{ id: 0 }]

參考

設計參考

• 不可使用陣列作為頂層回應