HTTP API 設計指南（響應部分）

這篇指南介紹描述了 http+json api 的一種設計模式，最初摘錄整理自 heroku 平台的 api 設計指引 heroku 平台 api 指引。

這篇指南除了詳細介紹現有的 api 外，heroku 將來新加入的內部 api 也會符合這種設計模式，我們希望非 heroku 員工的api設計者也能感興趣。

我們的目標是保持一致性，專注業務邏輯同時避免過度設計。我們一直試圖找出一種良好的、一致的、顯而易見的 api 設計方法，而並不是所謂的"最終/理想模式"。

我們假設你熟悉基本的 http+json api 設計方法，所以本篇指南並不包含所有的 api 設計基礎。

我們歡迎你為這篇指南做貢獻。

在預設情況給每乙個資源乙個id屬性。除非有更好的理由，否則請使用uuid。不要使用那種在伺服器上或是資源中不是全域性唯一的標識，尤其是自動增長的id。

生成小寫的uuid格式8-4-4-4-12，例如：

"id": "01234567-89ab-cdef-0123-456789abcdef"

為資源提供預設的建立時間created_at和更新時間updated_at，例如:

有些資源不需要使用時間戳那麼就忽略這兩個字段。

在接收和返回時都只使用utc格式。iso8601格式的資料，例如:

"finished_at": "2012-01-01t12:00:00z"

使用巢狀物件序列化外來鍵關聯，例如:

, // ... }

而不是像這樣:

, ... }

響應錯誤的時，生成統一的、結構化的錯誤資訊。包含乙個機器可讀的錯誤id，乙個人類能識別的錯誤資訊（message），根據情況可以新增乙個url來告訴客戶端關於這個錯誤的更多資訊以及如何去解決它，例如:

文件化客戶端可能遇到的錯誤資訊格式，以及這些可能的錯誤資訊id。

客戶端的訪問速度限制可以維護伺服器的良好狀態，保證為其他客戶端請求提供高性的服務。你可以使用token bucket algorithm技術量化請求限制。

為每乙個帶有ratelimit-remaining響應頭的請求，返回預留的請求tokens。

請求中多餘的空格會增加響應大小，而且現在很多的http客戶端都會自己輸出可讀格式（"prettify"）的json。所以最好保證響應json最小化，例如：

而不是這樣：

原文:

HTTP API 設計指南（基礎部分）

這篇指南介紹描述了 http json api 的一種設計模式，最初摘錄整理自 heroku 平台的 api 設計指引 heroku 平台 api 指引。這篇指南除了詳細介紹現有的 api 外，heroku 將來新加入的內部 api 也會符合這種設計模式，我們希望非 heroku 員工的api設計者...

HTTP API 設計指南（基礎部分）

為了保證持續和及時的更新，強烈推薦在我的github上關注該專案，歡迎各位star fork或者幫助翻譯這篇指南介紹描述了 http json api 的一種設計模式，最初摘錄整理自 heroku 平台的 api 設計指引 heroku 平台 api 指引。這篇指南除了詳細介紹現有的 api 外，...

HTTP API 設計指南（響應部分）

HTTP API 設計指南（基礎部分）

HTTP API 設計指南（基礎部分）

HTTP API 設計指南（結尾）

相關推薦