一区二区三区四区在线免费观看,久久综合噜噜激激的五月天,www.久久精品视频

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)請求狀態(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": "username@example.com",

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

  },

  ...

}

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

在默認(rèn)情況給每一個資源一個id屬性. 用此作為唯一標(biāo)識除非你有更好的理由不用.不要使用那種在服務(wù)器上或是資源中不是全局唯一的標(biāo)識，比如自動增長的id標(biāo)識。

返回的唯一標(biāo)識要用小寫字母并加個分割線格式?8-4-4-4-12, 例如.:

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

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

提供默認(rèn)的資源創(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)一的資源路徑

資源命名

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

形為

好的末尾展現(xiàn)形式不許要指定特殊的資源形為，在某些情況下，指定特殊的資源的形為是必須的,用一個標(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語言中不用輸入引號。例如.:

service_class: "first"

嵌套外鍵關(guān)系

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

{

  "name": "service-production",

  "owner": {

    "id": "5d8201b0..."

  },

  ...

}

而不是這樣例如:

{

  "name": "service-production",

  "owner_id": "5d8201b0...",

  ...

}

這種方式盡可能的把相關(guān)聯(lián)的資源信息內(nèi)聯(lián)在一起，而不用改變響應(yīng)資源的結(jié)構(gòu),或者展示更高一級的響應(yīng)區(qū)域, 例如:

{

  "name": "service-production",

  "owner": {

    "id": "5d8201b0...",

    "name": "Alice",

    "email": "alice@heroku.com"

  },

  ...

}

支持方便的無id間接引用

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

在網(wǎng)絡(luò)請求響應(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.service.com/rate-limits"

}

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

支持Etags緩存

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

用id來跟蹤每次的請求

在每一個API響應(yīng)中要包含一個Request-Id頭信息, 通常用唯一標(biāo)識UUID. 如果服務(wù)器和客戶端都打印出他們的Request-Id, 這對我們的網(wǎng)絡(luò)請求調(diào)試和跟蹤非常有幫助.

按范圍分頁

對于服務(wù)器響應(yīng)的大量數(shù)據(jù)我們應(yīng)該為此分頁。使用Content-Range?頭傳遞分頁請求的數(shù)據(jù).這里有個例子詳細(xì)的說明了請求和響應(yīng)頭、狀態(tài)碼，限制條件、排序以及分頁處理：Heroku Platform API on Ranges.

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

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

為每一個帶有RateLimit-Remaining響應(yīng)頭的請求，返回預(yù)留的請求tokens。

指定可接受頭信息的版本

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

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

最好不要給出一個默認(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概要

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

提供人類可讀的文檔

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

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

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

驗(yàn)證授權(quán),包含獲取及使用驗(yàn)證tokens.
API 穩(wěn)定性及版本控制, 包含如何選擇所需要的版本.
一般的請求和響應(yīng)頭信息.
錯誤信息序列格式.
不同語言客戶端使用API的例子.

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

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

$ export TOKEN=... # acquire from dashboard

$ curl -is https://$TOKEN@service.com/users

如果你使用prmd生成Markdown文檔, 你會自動獲取一些示例在結(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)定版本時, 不要在當(dāng)前API版本回退做一些不兼容的改變。如果你需要回退做一些不兼容的改變,請創(chuàng)建一個新的版本的API。

要求傳輸通道安全

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

使用友好的JSON輸出

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

{

  "beta": false,

  "email": "alice@heroku.com",

  "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@heroku.com","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友好的響應(yīng)數(shù)據(jù)輸出總會有更好的表現(xiàn)，你可能受到過不友好打印數(shù)據(jù)API的影響(例如:非常高的流量占用) 或者是在一些客戶端上不能工作 (例如：一個隨意編寫的程序).

本文章轉(zhuǎn)載微信公眾號@架構(gòu)師必備