word版可編輯-restfulapi設(shè)計(jì)規(guī)范精心整理(文件)
【正文】 信息等－這對(duì)于那些不容易訪問到返回頭的API使用者來說確實(shí)有用，但是隨著“標(biāo)準(zhǔn)”的發(fā)展（cors和），我個(gè)人推薦不要那么做。如果給出了這個(gè)參數(shù)，那么API應(yīng)該返回200，并且把真正的狀態(tài)碼放到返回值里面（包裝在信封里），例如：1234567callback_function({next_page: ://..,}})同樣為了支持無法方法返回頭的API使用者，可以允許envelope=true這樣的參數(shù)。這使得程序不得不根據(jù)字符串解析出布爾和整數(shù),而且還沒有層次結(jié)構(gòu)–雖然有一些關(guān)于層次結(jié)構(gòu)信息的約定存在可是和本身就支持層次結(jié)構(gòu)的json比較一下還是不很好用。注意使用json傳輸?shù)臅r(shí)候，要求請(qǐng)求頭里面加入：ContentType：application/json.，否則拋出415異常（unsupported media type）。這點(diǎn)在基于游標(biāo)的分頁中尤為重要。但是這卻和RESTful的原則相背。id : 12,summary : Hi, ....,},name : Jim,重寫HTTP方法有的客戶端只能發(fā)出簡單的GET 和POST請(qǐng)求。速度限制為了避免請(qǐng)求泛濫，給API設(shè)置速度限制很重要。加入速度設(shè)置之后，應(yīng)該提示用戶，至于如何提示標(biāo)準(zhǔn)上沒有說明，不過流行的方法是使用HTTP的返回頭。RFC 1123通過使用ssl我們可以不用每次都提供用戶名和密碼：我們可以給用戶返回一個(gè)隨機(jī)產(chǎn)生的token。支持jsonp的API需要額外的鑒權(quán)方法，因?yàn)閖sonp請(qǐng)求無法發(fā)送普通的credential。如果輸入的HTTP請(qǐng)求包含IFNONEMATCH頭以及一個(gè)ETag值，那么API應(yīng)該返回304 not modified狀態(tài)碼，而不是常規(guī)的輸出結(jié)果。時(shí)間戳，它和IFMODIFIEDSINCE一致。API的錯(cuò)誤碼可以分為兩部分，400系列和500系列，400系列表明客戶端錯(cuò)誤：如錯(cuò)誤的請(qǐng)求格式等。json格式的錯(cuò)誤應(yīng)該包含以下信息：一個(gè)有用的錯(cuò)誤信息，一個(gè)唯一的錯(cuò)誤碼，以及任何可能的詳細(xì)錯(cuò)誤描述。message : Password cannot be blank} 成功返回狀態(tài)，對(duì)應(yīng)，GET,PUT,PATCH,DELETE.成功創(chuàng)建。401 unauthorized 鑒權(quán)成功，但是該用戶沒有權(quán)限。404 not found 請(qǐng)求的資源不存在請(qǐng)求格式錯(cuò)誤。304 not modified ]}code : 5622,API應(yīng)該至少將所有的400系列的錯(cuò)誤以json形式返回。出錯(cuò)處理就像html錯(cuò)誤頁面能夠顯示錯(cuò)誤信息一樣，API 也應(yīng)該能返回可讀的錯(cuò)誤信息–它應(yīng)該和一般的資源格式一致。返回頭里的LastModified：包含了你需要做的是在返回的時(shí)候加入一些返回頭信息，在接受輸入的時(shí)候加入輸入驗(yàn)證。注意使用url參數(shù)的問題是：目前大部分的網(wǎng)絡(luò)服務(wù)器都會(huì)講query參數(shù)保存到服務(wù)器日志中，這可能會(huì)成為大的安全風(fēng)險(xiǎn)。這種方法適用于用戶可以首先通過一次用戶名密碼的驗(yàn)證并得到token，并且可以拷貝返回的token到以后的請(qǐng)求中。鑒權(quán)有些API使用UNIX格式時(shí)間戳，我建議不要那么干。 XRateLimitLimit :當(dāng)前時(shí)間段允許的并發(fā)請(qǐng)求數(shù)RFC 6585這里沒有什么標(biāo)準(zhǔn)，但是一個(gè)普遍的方式是接受XHTTPMethodOverride請(qǐng)求頭。}}值得提醒的是，這個(gè)功能有時(shí)候會(huì)很復(fù)雜，并且可能導(dǎo)致N+1 SELECT 問題。assigned_user: {name : Bobcustomer : {subject : I have a question!,embed可以是一個(gè)逗號(hào)分隔的串，例如：1GET /ticket/12embed=,assigned_user對(duì)應(yīng)的API返回值如下：123456789101112{ rel=next, 。分頁分頁數(shù)據(jù)可以放到“信封”里面，但隨著標(biāo)準(zhǔn)的改進(jìn)，現(xiàn)在我推薦將分頁信息放到link header里面：。但對(duì)于復(fù)雜的API你應(yīng)該使用json。很多的API使用url編碼格式：就像
公司管理相關(guān)推薦
鄂ICP備17016276號(hào)-1