為了保證持續(xù)和及時的更新，強(qiáng)烈推薦在我的Github上關(guān)注該項目，歡迎各位star/fork或者幫助翻譯
隔離關(guān)注點設(shè)計時通過將請求和響應(yīng)之間的不同部分隔離來讓事情變得簡單。保持簡單的規(guī)則讓我們能更關(guān)注在一些更大的更困難的問題上。 請求和響應(yīng)將解決一個特定的資源或集合。使用路徑（path）來表明身份，body來傳輸內(nèi)容（content）還有頭信息（header）來傳遞元數(shù)據(jù)（metadata）。查詢參數(shù)同樣可以用來傳遞頭信息的內(nèi)容，但頭信息是首選，因為他們更靈活、更能傳達(dá)不同的信息。 要求安全連接（Secure Connections）所有的訪問API行為，都需要用 TLS 通過安全連接來訪問。不值得去解釋什么時間需要 TLS 什么時候不需要 TLS，直接規(guī)定任何訪問都要求 TLS。 理想情況下，拒絕任何非 TLS 請求，不響應(yīng)基于 http 或是80端口的請求去避免任何不安全的數(shù)據(jù)交換。環(huán)境中不響應(yīng)的情況返回狀態(tài)403 Forbidden。 重定向是不推薦的，因為他們允許不好的客戶端的行為，不提供任何明確的目標(biāo)?？蛻粢蕾囍囟〞颖斗?wù)器流量和渲染 TLS 也沒有作用，因為敏感數(shù)據(jù)已經(jīng)無用在第一次調(diào)用已經(jīng)暴露。 要求接收頭信息中指定版本號版本和版本之間的過渡對于設(shè)計和操作API是一個非常大的挑戰(zhàn)。這樣，最好是開始時就有一些機(jī)制來緩和這個過渡。 為了防止意外,打破更改用戶，最好是與所有請求都需要指定一個版本。為了將來的修改，最好不要提供默認(rèn)的版本。 最好是在頭信息中指定版本號，和其它數(shù)據(jù)一起，通過Accepts自定義內(nèi)容類型(content type)同時傳遞，例如: Accept: application/vnd.heroku+json; version=3
支持Etag緩存在所有請求響應(yīng)中包含一個ETag頭，標(biāo)識出返回資源的版本。這樣就允許用戶去緩存這些資源，請求時將ETag的值設(shè)置到If-None-Match頭信息中就可以知道是否需要更新緩存了。 為內(nèi)省而提供 Request-Id為每一個請求響應(yīng)包含一個Request-Id字段，使用UUID作為該值。如果服務(wù)器和客戶端同時記錄下這些內(nèi)容，這樣對于跟蹤和調(diào)試請求非常有幫助。 為每一個請求響應(yīng)包含一個Request-Id字段，并使用UUID作為該值。通過在客戶端、服務(wù)器或任何支持服務(wù)上記錄該值，它能主我們提供一種機(jī)制來跟蹤、診斷和調(diào)試請求。 通過請求中的范圍（Range）拆分大的響應(yīng)一個大的響應(yīng)應(yīng)該通過多個請求使用Range頭信息來拆分，并指定如何取得。詳細(xì)的請求和響應(yīng)的頭信息（header），狀態(tài)碼(status code)，范圍(limit)，排序(ordering)和迭代(iteration)等，參考Heroku Platform API discussion of Ranges.
返回合適的狀態(tài)碼為每一次的響應(yīng)返回合適的HTTP狀態(tài)碼. 好的響應(yīng)應(yīng)該使用如下的狀態(tài)碼: 200: GET請求成功, 及DELETE或PATCH同步請求完成，或者PUT同步更新一個已存在的資源201: POST 同步請求完成，或者PUT同步創(chuàng)建一個新的資源202: POST, PUT, DELETE, 或 PATCH 請求接收，將被異步處理206: GET 請求成功, 但是只返回一部分，參考：上文中范圍分頁
使用身份認(rèn)證（authentication）和授權(quán)（authorization）錯誤碼時需要注意： 401 Unauthorized: 用戶未認(rèn)證，請求失敗403 Forbidden: 用戶無權(quán)限訪問該資源，請求失敗
當(dāng)用戶請求錯誤時，提供合適的狀態(tài)碼可以提供額外的信息： 422 Unprocessable Entity: 請求被服務(wù)器正確解析，但是包含無效字段429 Too Many Requests: 因為訪問頻繁，你已經(jīng)被限制訪問，稍后重試500 Internal Server Error: 服務(wù)器錯誤，確認(rèn)狀態(tài)并報告問題
對于用戶錯誤和服務(wù)器錯誤情況狀態(tài)碼，參考： HTTP response code spec 提供全部可用的資源提供全部可顯現(xiàn)的資源 (例如. 這個對象的所有屬性) ，當(dāng)響應(yīng)碼為200或是201時返回所有可用資源, 包含PUT/PATCH 和 DELETE
請求, 例如: $ curl -X DELETE \
https:
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)請求狀態(tài)碼為202時，不返回所有可用資源，例如： $ curl -X DELETE \
https:///apps/1f9b/dynos/05bd
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=utf-8
...
{}
在請求的body體使用JSON格式數(shù)據(jù)在 PUT/PATCH/POST 請求的正文（request bodies）中使用JSON格式數(shù)據(jù)，而不是使用 form 表單形式的數(shù)據(jù)。這與我們使用JSON格式返回請求相對應(yīng), 例如.: $ curl -X POST https:///apps -H "Content-Type: application/json" -d '{"name": "demoapp"}'
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "demoapp",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
...
}
使用統(tǒng)一的資源路徑格式資源名（Resource names）使用復(fù)制形式為資源命名，除非這個資源在系統(tǒng)中是單例的 (例如，在大多數(shù)系統(tǒng)中，給定的用戶帳戶只有一個)。 這種方式保持了特定資源的統(tǒng)一性。 形為（Actions）好的末尾展現(xiàn)形式不許要為某個資源指定特殊的形為，在某些特殊情況下，指定特殊的資源的形為是必須的，為了清楚的描述，用一個標(biāo)準(zhǔn)的actions前綴去放置他們: /resources/:resource/actions/:action
例如： /runs/{run_id}/actions/stop
路徑和屬性要小寫為了和域名對齊，使用小寫字母和-分割路徑名字，例如: service-api.com/users
service-api.com/app-setups
屬性同樣也要用小寫字母, 但是屬性名字要用下劃線_分割，因為這樣在JavaScript語言中不用輸入引號。 例如： service_class: "first"
支持方便的無id間接引用在某些情況下，讓用戶提供ID去定位資源是不方便的。例如，一個用戶想取得他在Heroku平臺app信息，但是這個app的唯一標(biāo)識是UUID。這種情況下，你應(yīng)該支持接口通過名字和ID都能訪問，例如: $ curl https:
$ curl https:
$ curl https:
不要只接受使用名字而放棄了使用id。 最小化路徑嵌套在一些有父路徑/子路徑嵌套關(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}
提供資源的(UU)ID在默認(rèn)情況給每一個資源一個id屬性。使用UUID除非你有更好的理由不用。不要使用那種在服務(wù)器上或是資源中不是全局唯一的標(biāo)識，尤其是自動增長的id。 生成小寫的UUID格式 8-4-4-4-12，例如： "id": "01234567-89ab-cdef-0123-456789abcdef"
提供標(biāo)準(zhǔn)的時間戳為資源提供默認(rèn)的創(chuàng)建時間 created_at 和更新時間 updated_at，例如: {
...
"created_at": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T13:00:00Z",
...
}
有些資源不需要使用時間戳那么就忽略這兩個字段。 使用UTC（世界標(biāo)準(zhǔn)時間）時間，用ISO8601進(jìn)行格式化在接收和返回時都只使用UTC格式。ISO8601格式的數(shù)據(jù)，例如: "finished_at": "2012-01-01T12:00:00Z"
嵌套外鍵關(guān)系使用嵌套對象序列化外鍵關(guān)聯(lián)，例如.: {
"name": "service-production",
"owner": {
"id": "5d8201b0..."
},
}
而不是像這樣: {
"name": "service-production",
"owner_id": "5d8201b0...",
...
}
這種方式盡可能的把相關(guān)聯(lián)的資源信息內(nèi)聯(lián)在一起，而不用改變資源的結(jié)構(gòu)，或者引入更多的字段 例如: {
"name": "service-production",
"owner": {
"id": "5d8201b0...",
"name": "Alice",
"email": "alice@heroku.com"
},
...
}
生成結(jié)構(gòu)化的錯誤響應(yīng)錯誤的時，生成統(tǒng)一的、結(jié)構(gòu)化的錯誤信息。包含一個機(jī)器可讀的錯誤 id，一個人類能識別的錯誤信息（message）, 根據(jù)情況可以添加一個url來告訴客戶端關(guān)于這個錯誤的更多信息以及如何去解決它，例如: HTTP/1.1 429 Too Many Requests
{
"id": "rate_limit",
"message": "Account reached its API rate limit.",
"url": "https://docs./rate-limits"
}
文檔化客戶端可能遇到的錯誤信息格式，以及這些可能的錯誤信息id。 顯示頻率限制狀態(tài)客戶端的訪問速度限制可以維護(hù)服務(wù)器的良好狀態(tài)，保證為其他客戶端請求提供高性的服務(wù)。你可以使用token bucket algorithm技術(shù)量化請求限制。 為每一個帶有RateLimit-Remaining響應(yīng)頭的請求，返回預(yù)留的請求tokens。 保證響應(yīng)JSON最小化請求中多余的空格會增加響應(yīng)大小，而且現(xiàn)在很多的HTTP客戶端都會自己輸出可讀格式（"prettify"）的JSON。所以最好保證響應(yīng)JSON最小化，例如： {"beta":false,"email":"alice@","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": "alice@",
"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"
}
你可以提供可選的方式為客戶端提供更詳細(xì)可讀的響應(yīng)，使用查詢參數(shù)（例如：?pretty=true）或者通過Accept頭信息參數(shù)（例如：Accept: application/vnd.heroku+json; version=3; indent=4;）。
提供機(jī)器可讀的JSON模式提供一個機(jī)器可讀的模式來恰當(dāng)?shù)谋憩F(xiàn)你的API.使用
prmd管理你的模式, 并且確保用prmd verify驗證是有效的。 提供人類可讀的文檔提供人類可讀的文檔讓客戶端開發(fā)人員可以理解你的API。 如果你用prmd創(chuàng)建了一個概要并且按上述要求描述，你可以為所有節(jié)點很容易的使用prmd doc生成Markdown文檔。 除了節(jié)點信息，提供一個API概述信息: - 驗證授權(quán)，包含如何取得和如何使用token。
- API穩(wěn)定及版本管理，包含如何選擇所需要的版本。
- 一般情況下的請求和響應(yīng)的頭信息。
- 錯誤的序列化格式。
- 不同編程語言客戶端使用API的例子。
提供可執(zhí)行的例子提供可執(zhí)行的示例讓用戶可以直接在終端里面看到API的調(diào)用情況，最大程度的讓這些示例可以簡單的使用，以減少用戶嘗試使用API的工作量。例如: $ export TOKEN=...
$ curl -is https://$TOKEN@/users
如果你使用prmd生成Markdown文檔, 每個節(jié)點都會自動獲取一些示例。 描述穩(wěn)定性描述您的API的穩(wěn)定性或是它在各種各樣節(jié)點環(huán)境中的完備性和穩(wěn)定性，例如：加上 原型版（prototype）/開發(fā)版（development）/產(chǎn)品版（production）等標(biāo)記。 更多關(guān)于可能的穩(wěn)定性和改變管理的方式，查看 Heroku API compatibility policy 一旦你的API宣布產(chǎn)品正式版本及穩(wěn)定版本時, 不要在當(dāng)前API版本中做一些不兼容的改變。如果你需要，請創(chuàng)建一個新的版本的API。 |
