HTTP API 設計指南（結尾）

爲了保證持續和及時的更新，強烈推薦在個人Github上關注該項目，歡迎各位star/fork或者幫助翻譯

前言

這篇指南介紹描述了 HTTP+JSON API 的一種設計模式，最初摘錄整理自 Heroku 平臺的 API 設計指引 Heroku 平臺 API 指引。

這篇指南除了詳細介紹現有的 API 外，Heroku 未來新加入的內部 API 也會符合這種設計模式，咱們但願非 Heroku 員工的API設計者也能感興趣。

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

咱們假設你熟悉基本的 HTTP+JSON API 設計方法，因此本篇指南並不包含全部的 API 設計基礎。

咱們歡迎你爲這篇指南作貢獻。

---

提供機器可讀的JSON模式

提供一個機器可讀的模式來恰當的表現你的API。使用
prmd管理你的模式，而且確保用prmd verify驗證是有效的。

提供人類可讀的文檔

提供人類可讀的文檔讓客戶端開發人員能夠理解你的API。

若是你用prmd建立了一個概要而且按上述要求描述，你能夠爲全部節點很容易的使用prmd doc生成Markdown文檔。

除了節點信息，提供一個API概述信息:

• 驗證受權，包含如何取得和如何使用token。

• API穩定及版本管理，包含如何選擇所須要的版本。

• 通常狀況下的請求和響應的頭信息。

• 錯誤的序列化格式。

• 不一樣編程語言客戶端使用API的例子。

提供可執行的例子

提供可執行的示例讓用戶能夠直接在終端裏面看到API的調用狀況，最大程度的讓這些示例能夠簡單的使用，以減小用戶嘗試使用API的工做量。例如:

$ export TOKEN=... # acquire from dashboard
$ curl -is https://$TOKEN@service.com/users

若是你使用prmd生成Markdown文檔，每一個節點都會自動獲取一些示例。

描述穩定性

描述您的API的穩定性或是它在各類各樣節點環境中的完備性和穩定性，例如：加上 原型版（prototype）/開發版（development）/產品版（production）等標記。

更多關於可能的穩定性和改變管理的方式，查看 Heroku API compatibility policy

一旦你的API宣佈產品正式版本及穩定版本時，不要在當前API版本中作一些不兼容的改變。若是你須要，請建立一個新的版本的API。