http-api-design
  • Introduction
  • Summary
    • 簡介
    • 基礎
      • 重心分離
      • 要求使用安全連線
      • 要求以 Accept 標頭註明版本
      • 以 ETag 支援快取
      • 提供 Request-Id 以便追溯
      • 以 Range 分割資料量大的回應
    • 需求
      • 回傳適當的狀態碼
      • 情況許可時提供全部資源
      • 接受需求本體的序列化 JSON
      • 使用一致的路徑格式
      • 小寫路徑與屬性
      • 支援非 ID 的便利存取
      • 減少巢狀路徑
    • 回應
      • 提供資源的 UUID
      • 提供標準時間戳記
      • 使用 UTC 時間並以 ISO 8601 格式表達
      • 巢狀表示外來鍵關係
      • 產生結構化的錯誤訊息
      • 顯示次數限制狀態
      • 保持所有回應中的 JSON 最小化
    • 產出
      • 提供機器可讀的 JSON 大綱
      • 提供一般人可讀的文件
      • 提供執行範例
      • 描述穩定性
Powered by GitBook
On this page

Was this helpful?

  1. Summary
  2. 需求

情況許可時提供全部資源

盡可能於回應裡呈現全部資源 (意即物件的所有屬性)。永遠於 200 與 201 回應提供全部資源,其中包含 PUT、PATCH 和 DELETE 需求,例如:

$ curl -X DELETE \  
  https://service.com/apps/1f9b/domains/0fd4

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
...
{
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

202 回應不會完整呈現全部資源,例如:

$ curl -X DELETE \  
  https://service.com/apps/1f9b/dynos/05bd

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=utf-8
...
{}
Previous回傳適當的狀態碼Next接受需求本體的序列化 JSON

Last updated 5 years ago

Was this helpful?