HTTP API 設(shè)計(jì)指南

相關(guān)閱讀：一款神仙接私活低代碼平臺(tái)，吊到不行（附源碼）

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

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

對(duì)于用戶請(qǐng)求的錯(cuò)誤情況，及服務(wù)器的異常錯(cuò)誤情況，請(qǐng)查閱完整的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"
}

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

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

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

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

在 PUT/PATCH/POST 請(qǐng)求的body體使用JSON格式數(shù)據(jù), 而不是使用 form 表單形式的數(shù)據(jù). 這里我們使用JSON格式的body請(qǐng)求創(chuàng)建對(duì)稱的格式數(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"
  },
  ...
}

提供資源的唯一標(biāo)識(shí)

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

提供標(biāo)準(zhǔn)的時(shí)間戳

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

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

使用ISO8601的國際化時(shí)間格式

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

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

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

資源命名

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

形為

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

/resources/:resource/actions/:action

例如.

/runs/{run_id}/actions/stop

路徑和屬性要用小寫字母

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

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

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

service_class: "first"

嵌套外鍵關(guān)系

序列化的外鍵關(guān)系通常建立在一個(gè)有嵌套關(guān)系的對(duì)象之上, 例如.:

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

而不是這樣 例如:。另外，搜索公眾號(hào)互聯(lián)網(wǎng)架構(gòu)師后臺(tái)回復(fù)“面試”，獲取一份驚喜禮包

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

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

支持方便的無id間接引用

在某些情況下，為了方便用戶使用接口，在末尾提供用id標(biāo)識(shí)資源,例如，一個(gè)用戶想到了他在heroku平臺(tái)app的名字，但是這個(gè)app的唯一標(biāo)識(shí)是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。

構(gòu)建錯(cuò)誤信息

在網(wǎng)絡(luò)請(qǐng)求響應(yīng)錯(cuò)誤的時(shí)候，返回統(tǒng)一的，結(jié)構(gòu)化的錯(cuò)誤信息。要包含一個(gè)機(jī)器可讀的錯(cuò)誤 id,一個(gè)人類能識(shí)別的錯(cuò)誤信息 message, 根據(jù)情況可以添加一個(gè)url ，告訴客戶端關(guān)于這個(gè)錯(cuò)誤的更多信息以及如何去解決它。例如:

HTTP/1.1 429 Too Many Requests

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

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

支持Etags緩存

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

用id來跟蹤每次的請(qǐng)求

按范圍分頁

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

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

指定可接受頭信息的版本

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

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

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

減少路徑嵌套

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

/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}

提供機(jī)器可讀的JSON概要

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

提供人類可讀的文檔

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

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

除此之在詳細(xì)信息的結(jié)尾，提供一個(gè)關(guān)于如下信息的API摘要:

• 驗(yàn)證授權(quán),包含獲取及使用驗(yàn)證tokens.

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

• 一般的請(qǐng)求和響應(yīng)頭信息.

• 錯(cuò)誤信息序列格式.

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

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

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

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

如果你使用prmd生成Markdown文檔, 你會(huì)自動(dòng)獲取一些示例在結(jié)點(diǎn)處。

描述穩(wěn)定性

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

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

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

要求傳輸通道安全

要求在傳輸通道安全的情況下訪問API,這點(diǎn)沒什么可解釋的了. 因?yàn)檫@不值得去爭(zhēng)辯在什么時(shí)候使用傳輸通道安全訪問API是好的，什么時(shí)候是不好的，只需要記住在訪問API時(shí)，使用安全傳輸通道就行了。

使用友好的JSON輸出

用戶在第一次看到你的API使用情況，很可能是在命令行下使用curl進(jìn)行的。友好的輸出會(huì)讓他們非常容易的理解你的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"}

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

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

-End-