HTTP API 設計指南

返回合適的狀態(tài)碼

• 200: GET請求成功, 以及DELETE或 PATCH 同步請求完成
• 201: POST 同步請求完成
• 202: POST, DELETE, 或 PATCH 異步請求將要完成
• 206: GET 請求成功, 這里只是一部分狀態(tài)碼: 更多

對于用戶請求的錯誤情況，及服務器的異常錯誤情況，請查閱完整的HTTP狀態(tài)碼HTTP response code spec。

提供全部可用的資源

$ 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"
}

當請求狀態(tài)碼為202時，不返回所有可用資源, e.g.:

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

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=utf-8
...
{}

在請求的body體使用JSON數(shù)據(jù)

在 PUT/PATCH/POST 請求的body體使用JSON格式數(shù)據(jù), 而不是使用 form 表單形式的數(shù)據(jù). 這里我們使用JSON格式的body請求創(chuàng)建對稱的格式數(shù)據(jù), 例如.:

$ curl -X POST https://service.com/apps \
    -H "Content-Type: application/json" \
    -d '{"name": "demoapp"}'

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "demoapp",
  "owner": {
    "email": "[email protected]",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  ...
}

提供資源的唯一標識

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

提供標準的時間戳

提供默認的資源創(chuàng)建時間，更新時間 created_at and updated_at , e例如:

{
  ...
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T13:00:00Z",
  ...
}

使用ISO8601的國際化時間格式

在接收的返回時間數(shù)據(jù)時只使用UTC格式. 查閱ISO8601時間格式, 例如:

"finished_at": "2012-01-01T12:00:00Z"

使用統(tǒng)一的資源路徑

資源命名

使用復數(shù)形式為資源命名，而不是在系統(tǒng)中有爭議的一個單個資源 (例如，在大多數(shù)系統(tǒng)中，給定的用戶帳戶只有一個). 這種方式保持了特定資源的統(tǒng)一性.

形為

好的末尾展現(xiàn)形式不許要指定特殊的資源形為，在某些情況下，指定特殊的資源的形為是必須的,用一個標準的actions前綴去替代他, 清楚的描述他:

/resources/:resource/actions/:action

例如.

/runs/{run_id}/actions/stop

路徑和屬性要用小寫字母

使用小寫字母并用-短線分割路徑名字,并且緊跟著主機域名 e.g:

service-api.com/users
service-api.com/app-setups

同樣屬性也要用小寫字母, 但是屬性名字要用下劃線_分割，以至于這樣在javaScript語言中不用輸入引號。例如.:

service_class: "first"

嵌套外鍵關系

序列化的外鍵關系通常建立在一個有嵌套關系的對象之上, 例如.:

{
  "name": "service-production",
  "owner": {
    "id": "5d8201b0..."
  },
  ...
}

而不是這樣 例如:。另外，搜索公眾號互聯(lián)網架構師后臺回復“面試”，獲取一份驚喜禮包

{
  "name": "service-production",
  "owner_id": "5d8201b0...",
  ...
}

{
  "name": "service-production",
  "owner": {
    "id": "5d8201b0...",
    "name": "Alice",
    "email": "[email protected]"
  },
  ...
}

支持方便的無id間接引用

在某些情況下，為了方便用戶使用接口，在末尾提供用id標識資源,例如，一個用戶想到了他在heroku平臺app的名字，但是這個app的唯一標識是id,這種情況下，你想讓接口通過名字和id都能訪問，例如:

$ curl https://service.com/apps/{app_id_or_name}
$ curl https://service.com/apps/97addcf0-c182
$ curl https://service.com/apps/www-prod

不要只接受使用名字而剔除了使用id。

構建錯誤信息

在網絡請求響應錯誤的時候，返回統(tǒng)一的，結構化的錯誤信息。要包含一個機器可讀的錯誤 id,一個人類能識別的錯誤信息 message, 根據(jù)情況可以添加一個url ，告訴客戶端關于這個錯誤的更多信息以及如何去解決它。例如:

HTTP/1.1 429 Too Many Requests

{
  "id":      "rate_limit",
  "message": "Account reached its API rate limit.",
  "url":     "https://docs.service.com/rate-limits"
}

把你的錯誤信息格式文檔化，以及這些可能的錯誤信息ids 讓客戶端能獲取到.

支持Etags緩存

在所有請求響應中包含一個ETag頭,比如，標識出返回資源的指定版本. 用戶能夠根據(jù)他們提供的頭信息If-None-Match，在隨后的請求中檢查出那些無效的。

用id來跟蹤每次的請求

按范圍分頁

顯示速度限制狀態(tài)

客戶端的訪問速度限制可以維護服務器的良好狀態(tài)，進而為其他客戶端請求提供高性的服務.你可以使用token bucket algorithm技術量化請求限制.

指定可接受頭信息的版本

在開始的時候指定API版本，使用Accepts頭傳遞版本信息,也可以是一個自定義的內容, 例如:

Accept: application/vnd.heroku+json; version=3

最好不要給出一個默認的版本, 而是要求客戶端明確指明他們要使用特定的版本.

減少路徑嵌套

在一些有父路徑/子路徑嵌套關系的資源數(shù)據(jù)模塊中, 路徑可能有非常深的嵌套關系, 例如:

/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}

推薦在根(root)路徑下指定資源來限制路徑的嵌套深度。使用嵌套指定范圍的資源，例如在下面的情況下，dyno屬性app范圍下，app屬性org范圍下:

/orgs/{org_id}
/orgs/{org_id}/apps
/apps/{app_id}
/apps/{app_id}/dynos
/dynos/{dyno_id}

提供機器可讀的JSON概要

提供一個機器可讀的概要恰當?shù)谋憩F(xiàn)你的API.使用 prmd管理你的概要, 并且確保用prmd verify驗證是有效的。

提供人類可讀的文檔

提供人類可讀的文檔讓客戶端開發(fā)人員可以理解你的API。

如果你用prmd創(chuàng)建了一個概要并且按上述要求描述，你可以很容易的生成所有結節(jié)使用prmd doc的Markdown文件。

除此之在詳細信息的結尾，提供一個關于如下信息的API摘要:

• 驗證授權,包含獲取及使用驗證tokens.

• API 穩(wěn)定性及版本控制, 包含如何選擇所需要的版本.

• 一般的請求和響應頭信息.

• 錯誤信息序列格式.

• 不同語言客戶端使用API的例子.

提供可執(zhí)行的示例

提供可執(zhí)行的示例讓用戶可以直接在終端里面看到API的調用情況,最大程度的讓這些示例可以逐字的使用，以減少用戶嘗試使用API的工作量。例如:

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

如果你使用prmd生成Markdown文檔, 你會自動獲取一些示例在結點處。

描述穩(wěn)定性

描述您的API的穩(wěn)定性或是它在各種各樣節(jié)點環(huán)境中的完備性和穩(wěn)定性 例如. 帶有 原型/開發(fā)版/產品 等標簽.

更多關于可能的穩(wěn)定性和改變管理的方式，查看 Heroku API compatibility policy

一旦你的API宣布產品正式版本及穩(wěn)定版本時, 不要在當前API版本回退做一些不兼容的改變。如果你需要回退做一些不兼容的改變,請創(chuàng)建一個新的版本的API。

要求傳輸通道安全

要求在傳輸通道安全的情況下訪問API,這點沒什么可解釋的了. 因為這不值得去爭辯在什么時候使用傳輸通道安全訪問API是好的，什么時候是不好的，只需要記住在訪問API時，使用安全傳輸通道就行了。

使用友好的JSON輸出

用戶在第一次看到你的API使用情況，很可能是在命令行下使用curl進行的。友好的輸出會讓他們非常容易的理解你的API，為好開發(fā)者們的方便,打印友好的JSON輸出, 例如:

{
  "beta": false,
  "email": "[email protected]",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "last_login": "2012-01-01T12:00:00Z",
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T12:00:00Z"
}

而不是這樣 例如:

{"beta":false,"email":"[email protected]","id":"01234567-89ab-cdef-0123-456789abcdef","last_login":"2012-01-01T12:00:00Z", "created_at":"2012-01-01T12:00:00Z","updated_at":"2012-01-01T12:00:00Z"}

記住要在每行尾部包含一個換行，這樣那些使用終端測試API的輸出不會被遮擋住。

對于大多數(shù)的API友好的響應數(shù)據(jù)輸出總會有更好的表現(xiàn)，你可能受到過不友好打印數(shù)據(jù)API的影響(例如:非常高的流量占用) 或者是在一些客戶端上不能工作 (例如：一個隨意編寫的程序).