word版可編輯-restfulapi設(shè)計(jì)規(guī)范精心整理(編輯修改稿)
2025-05-04 06:53 本頁(yè)面
【文章內(nèi)容簡(jiǎn)介】 GET /ticketsfields=id,subject,customer_name,updated_atamp。state=openamp。sort=updated_at更新和創(chuàng)建操作應(yīng)該返回資源PUT、POST、PATCH 操作在對(duì)資源進(jìn)行操作的時(shí)候常常有一些副作用：例如created_at,updated_at 時(shí)間戳。為了防止用戶多次的API調(diào)用（為了進(jìn)行此次的更新操作），我們應(yīng)該會(huì)返回更新的資源（updated representation.）例如：在POST操作以后，返回201 created 狀態(tài)碼，并且包含一個(gè)指向新資源的url作為返回頭是否需要 “HATEOAS“網(wǎng)上關(guān)于是否允許用戶創(chuàng)建新的url有很大的異議（注意不是創(chuàng)建資源產(chǎn)生的url）。為此REST制定了HATEOAS來(lái)描述了和endpoint進(jìn)行交互的時(shí)候，行為應(yīng)該在資源的metadata返回值里面進(jìn)行定義。（譯注：作者這里認(rèn)為HATEOAS還不算成熟，我也不怎么理解這段就算了，讀者感興趣可以自己去原文查看）只提供json作為返回格式現(xiàn)在開(kāi)始比較一下XML和json了。XML即冗長(zhǎng)，難以閱讀，又不適合各種編程語(yǔ)言解析。當(dāng)然XML有擴(kuò)展性的優(yōu)勢(shì)，但是如果你只是將它來(lái)對(duì)內(nèi)部資源串行化，那么他的擴(kuò)展優(yōu)勢(shì)也發(fā)揮不出來(lái)。很多應(yīng)用（youtube,twitter,box）都已經(jīng)開(kāi)始拋棄XML了，我也不想多費(fèi)口舌。給了google上的趨勢(shì)圖吧：當(dāng)然如果的你使用用戶里面企業(yè)用戶居多，那么可能需要支持XML。如果是這樣的話你還有另外一個(gè)問(wèn)題：你的請(qǐng)求中的media類型是應(yīng)該和accept 頭同步還是和url？為了方便（browser explorability）,應(yīng)該是在url中(用戶只要自己拼url就好了)。命名方式？是蛇形命令（下劃線和小寫）還是駝峰命名？如果使用json那么最好的應(yīng)該是遵守JAVASCRIPT的命名方法也就是說(shuō)駱駝命名法。如果你正在使用多種語(yǔ)言寫一個(gè)庫(kù)，那么最好按照那些語(yǔ)言所推薦的，java，c使用駱駝，python，ruby使用snake。個(gè)人意見(jiàn)：我總覺(jué)得蛇形命令更好使一些，當(dāng)然這沒(méi)有什么理論的依據(jù)。有人說(shuō)蛇形命名讀起來(lái)更快，能達(dá)到20%，也不知道真假默認(rèn)使用pretty print格式，使用gzip只是使用空格的返回結(jié)果從瀏覽器上看總是覺(jué)得很惡心(一大坨有沒(méi)有？～)。當(dāng)然你可以提供url上的參數(shù)來(lái)控制使用“pretty print”，但是默認(rèn)開(kāi)啟這個(gè)選項(xiàng)還是更加友好。格外的傳輸上的損失不會(huì)太大。相反你如果忘了使用gzip那么傳輸效率將會(huì)大大減少，損失大大增加。想象一個(gè)用戶正在debug那么默認(rèn)的輸出就是可讀的而不用將結(jié)果拷貝到其他什么軟件中在格式化是想起來(lái)就很爽的事，不是么？下面是一個(gè)例子:$ curl $ ruby r json e 39。puts JSON ()39。 $ gzip c $ gzip c 輸出如下： 1252 bytes 1369 bytes 496 bytes 509 bytes在上面的例子中，%（沒(méi)有使用gzip），%。據(jù)說(shuō)：twitter使用gzip之后它的streaming API傳輸減少了80%（link:）.只在需要的時(shí)候使用“envelope”很多API象下面這樣返回結(jié)果：123456{data : {id : 123,name : John}}理由很簡(jiǎn)單：這樣做可以很容易擴(kuò)展返回結(jié)果，你可以加入一些分頁(yè)信息，一些數(shù)據(jù)的元信息等－這對(duì)于那些不容易訪問(wèn)到返回頭的API使用者來(lái)說(shuō)確實(shí)有用，但是隨著“標(biāo)準(zhǔn)”的發(fā)展（cors和），我個(gè)人推薦不要那么做。何時(shí)使用envelope？有兩種情況是應(yīng)該使用envelope的。如果API使用者確實(shí)無(wú)法訪問(wèn)返回頭，或者API需要支持交叉域請(qǐng)求（通過(guò)jsonp）。jsonp請(qǐng)求在請(qǐng)求的url中包含了一個(gè)callback函數(shù)參數(shù)。如果給出了這個(gè)參數(shù)，那么API應(yīng)該返回200，并且把真正的狀態(tài)碼放到返回值里面（包裝在信封里），例如：1234567callback_function({status_code: 200,next_page: ://..,response: {160
公司管理相關(guān)推薦
鄂ICP備17016276號(hào)-1