摘要:最佳實踐漸漸成為向外曝露服務(wù)的通用方式。有效的使用狀態(tài)碼定義了非常多的狀態(tài)碼,這些碼對客戶端非常有意義。下面是狀態(tài)碼的列表和摘要表示對應(yīng)的或操作成功。
REST API最佳實踐
REST漸漸成為向外曝露服務(wù)的通用方式。之所以這么流行的原因主要是簡單,易于使用,使用HTTP協(xié)議(REST可以用于所有協(xié)議,但應(yīng)用最廣泛的是HTTP)等。但是所有向外暴露的資源都被認為是REST是一種誤解,是不正確的。在這里,我會向你介紹一些在你實現(xiàn)自己的REST API時你應(yīng)該謹記的最佳實踐。
擴展閱讀:REST vs SOAP
下面是一個導讀列表
1.名詞,不要用動詞
2.使用復數(shù)
3.文檔
4.接口版本
5.分頁
6.使用SSL
7.HTTP方法
8.有效的使用HTTP狀態(tài)碼
1.名詞,不要動詞REST API開發(fā)人員的一個不好的習慣是使用動詞來命名REST接口。你應(yīng)該使用名詞來替代動詞。
場景要新建一個REST web services用來獲取印度的農(nóng)民數(shù)據(jù)。同時,該接口也可以獲取其他的信息比如收入,農(nóng)作物名稱,地址等和農(nóng)民相關(guān)的數(shù)據(jù)。每一個農(nóng)民都指派了unique ID。
同樣的,服務(wù)也需要提供農(nóng)民關(guān)聯(lián)的農(nóng)作物的信息的接口。
為所有的操作提供單一的endpoint.在下面的例子中,我們?yōu)樗械牟僮鳎╣et,add,update,delete)提供了一個endpoint "/farmers",通過不同的HTTP method 來調(diào)用不同的操作,下面還會詳細介紹。
/farmers
/crops
盡量避免盡量避免在命名中使用動詞。推薦在數(shù)據(jù)中或者HTTP method提現(xiàn)操作。不要像下面這樣命名REST
/getFarmers
/updateFarmers
/deleteFarmers
2.使用復數(shù)使用復數(shù)來命名REST服務(wù)。這是在REST設(shè)計者討論中的熱門話題。
最佳實踐/farmers
/farmers/{farmer_id}
盡量避免/farmer
/farmer/{farmer_id}
注意在實踐中不要混用單數(shù)或者復數(shù)命名,雖然我說使用復數(shù)是最佳實踐,但是如果你堅持使用單數(shù),那么就在所有的服務(wù)上執(zhí)行相同的策略。
3.文檔對軟件實現(xiàn)文檔化是非常好的習慣,對REST API也是同樣。如果你寫下了有用的文檔,這將使其他開發(fā)者收益。對于REST API的常見注釋,主要是列出API的endpoints,對每一個endpoint描述其支持的功能列表。有很多工具可以自動完成這件事情。這些工具有:DRF DOCs,Swagger,Apiary
4.接口版本任何軟件都會進化,對于API的每一個比較大的變動,可能需要不同的版本號。如果對API版本化,是REST開發(fā)者社區(qū)的熱門話題。一般來說,有兩種方法來將接口版本化
URI 版本化使用URI的簡單例子是
http://host/v2/farmers
http://host/v1/farmers
主要的缺點有
破壞了存在的URI,所有的客戶端需要跟著改
增加了需要管理的URI,這會導致增加客戶端保存多個URI版本的緩存增加。會降低緩存的命中率,也會降低應(yīng)用的運行效率。
非常不具彈性,不能簡單的修改單個資源或者資源的子集。
媒體類型版本化這個方法是通過在request的header上增加接口的版本信息。當我們改變URI的資源類型和語言時,我們要修改request的頭信息。這個方法對于REST API的版本化是最好的選擇。
媒體類型不再是application/json,而是像下面這樣:
GET /account/5555 HTTP/1.1
Accept: application/vnd.farmers.v1+json
HTTP/1.1 200 OK
Content-Type: application/vnd.farmers.v1+json
通過這個方法,客戶端可以選擇要請求的版本。雖說這個方法比URI版本化來得好,但是通過header傳輸?shù)牟煌姹镜恼埱缶彺娴膹碗s度也大大上升了。簡單的說,當客戶端基于URI做緩存,這是簡單的,但是通過媒體類型來緩存就增加了復雜性。
通過HTTP發(fā)送大量數(shù)據(jù)是一個糟糕的做法。這會引發(fā)性能問題,因為序列化大的json對象非常耗時耗資源。建議將結(jié)果分頁并提供前后的導航鏈接。
如果你在應(yīng)用中使用分頁,一個較好的做法是使用Link HTTP header option. 這篇文章 link from GitHub應(yīng)該有用。會幫你打開思路。
使用SSL是必須的。REST API必須得到SSL的保護。引用在因特網(wǎng)上發(fā)布,無法保證安全的接入。隨著越來越多的計算機犯罪事件,我們必須以正確的方式來保護我們的應(yīng)用。
API的安全已經(jīng)有成熟的工業(yè)標準。不要使用簡單的認證機制。可以使用Oauth1.0a或者Oauth2來使接口變得安全。建議使用最新的Oauth2。
當你知道各個HTTP方法所扮演的角色后,將操作映射到HTTP的方法是非常簡單的。在前面提及要使用HTTP方法來表示資源的操作,而不是通過不同的服務(wù)名字。本節(jié)會大致介紹各個HTTP方法的行為模式。
下面兩點是在使用HTTP方法前需要考慮的兩個方面:
安全 :當調(diào)用方法時不會改變資源的狀態(tài),就認為該HTTP方法時安全的。比如,當通過GET方法獲取數(shù)據(jù),因為不會修改數(shù)據(jù),所以這個方法就是安全的。
冪等 :調(diào)用資源多次,所獲得的回應(yīng)是相同的,這就是冪等。比如,當你嘗試更新數(shù)據(jù),每次的返回都相同。
不是所有的方法都是安全和冪等的。下面是一個可以用在REST API調(diào)用的列表,表示各個方法安全和冪等的情況
GET 安全 冪等 POST 不安全 不冪等 PUT 不安全 冪等 DELETE 不安全 冪等 OPTIONS 安全 冪等 HEAD 安全 冪等
下面是各個方法的簡要說明,在使用的時候請參考:
GET:這個方法是安全且冪等的。常用于獲取數(shù)據(jù)。
POST:這個方法不安全也不冪等。常用于創(chuàng)建資源。
PUT:這個方法是冪等。常用于更新資源。需要避免使用POST來更新資源。
DELETE:常用語刪除資源,但是這個方法并不是對所有的請求冪等的。
OPTIONS:這個方法不是用來操作資源的。當客戶端不清楚對應(yīng)的資源有哪些操作時,使用該操作獲得資源的表示。
HEAD:可以用來查詢一個資源。和GET非常想,但是就如在HTTP的規(guī)定所解釋的,HEAD方法必須在header中發(fā)送請求和獲得回應(yīng)。
8.有效的使用HTTP狀態(tài)碼HTTP定義了非常多的狀態(tài)碼,這些碼對客戶端非常有意義。你的REST API可以有效的使用這些狀態(tài)碼來幫助客戶端。下面是狀態(tài)碼的列表和摘要:
200 OK - 表示對應(yīng)的GET,PUT,PATCH 或 DELETE操作成功。也可以用于POST表示沒有創(chuàng)建成功。
201 Created - 表示POST創(chuàng)建成功
204 No Content - 表示一個成功的響應(yīng),body為空(比如 delete)
304 Not Modified - HTTP緩存
400 Bad Request - 表示request錯誤,比如body解析出錯
401 Unauthorized - 提供了錯誤的認證信息。可以在這個錯誤之后觸發(fā)認證功能。
403 Forbidden - 當認證成功,但是對應(yīng)的用戶沒有對應(yīng)資源的權(quán)限時。
404 Not Found - 表示請求一個并不存在的資源
405 Method Not Allowed - 一個認證的用戶,調(diào)用了他所不允許使用的方法時。
410 Gone - 表示資源已經(jīng)不可用。比如調(diào)用了一個老的API版本。
415 Unsupported Media Type - request提供了錯誤的content type
422 Unprocessable Entity - 驗證錯誤
429 Too Many Requests - 因為負載限制,拒絕request時。
文章版權(quán)歸作者所有,未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為,您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請注明本文地址:http://specialneedsforspecialkids.com/yun/70479.html
摘要:要對進行黑盒測試測試的最好辦法是對他們進行黑盒測試,黑盒測試是一種不關(guān)心應(yīng)用內(nèi)部結(jié)構(gòu)和工作原理的測試方法,測試時系統(tǒng)任何部分都不應(yīng)該被。此外,有了黑盒測試并不意味著不需要單元測試,針對的單元測試還是需要編寫的。 本文首發(fā)于之乎專欄前端周刊,全文共 6953 字,讀完需 8 分鐘,速度需 2 分鐘。翻譯自:RingStack 的文章 https://blog.risingstack.co...
showImg(https://segmentfault.com/img/bV6aHV?w=1280&h=800); 社區(qū)優(yōu)秀文章 Laravel 5.5+passport 放棄 dingo 開發(fā) API 實戰(zhàn),讓 API 開發(fā)更省心 - 自造車輪。 API 文檔神器 Swagger 介紹及在 PHP 項目中使用 - API 文檔撰寫方案 推薦 Laravel API 項目必須使用的 8 個...
摘要:現(xiàn)在開始創(chuàng)建一個包并分發(fā)給其他人使用,并確保遵循你迄今為止學到的標準和最佳實踐。第步實踐對于練習,繼續(xù)編寫單元測試,以完成目前為止所做的實際任務(wù),特別是你在步驟中所做的練習。 今天的Web開發(fā)與幾年前完全不同,有很多不同的東西可以很容易地阻止任何人進入Web開發(fā)。這是我們決定制作這些循序漸進的視覺指南的原因之一,這些指南展示了更大的圖景,并讓任何人清楚了解他們在網(wǎng)頁開發(fā)中扮演的角色。 ...
摘要:簡評之前,后端開發(fā)路線圖僅僅是一個技術(shù)推薦,且沒有明確的方向指明應(yīng)該遵循的順序,這份重新制作的指南將會給你一個更好的方向。現(xiàn)在開始創(chuàng)建一個包并分發(fā)給其他人使用,并確保遵循迄今為止學到的標準和最佳實踐。 簡評:之前,后端開發(fā)路線圖僅僅是一個技術(shù)推薦,且沒有明確的方向指明應(yīng)該遵循的順序,這份重新制作的指南將會給你一個更好的方向。 現(xiàn)在的 Web 開發(fā)與幾年前完全不同了,有很多不同的東西可以...
摘要:不過今天我希望能夠更進一步,不僅僅再抱怨現(xiàn)狀,而是從我個人的角度來給出一個逐步深入學習生態(tài)圈的方案。最后,我還是想提到下對于的好的學習方法就是回顧參照各種各樣的代碼庫,學習人家的用法與實踐。 本文翻譯自A-Study-Plan-To-Cure-JavaScript-Fatigue。筆者看到里面的幾張配圖著實漂亮,順手翻譯了一波。本文從屬于筆者的Web Frontend Introduc...
閱讀 866·2021-11-15 11:37
閱讀 3604·2021-11-11 16:55
閱讀 3270·2021-11-11 11:01
閱讀 999·2019-08-30 15:43
閱讀 2743·2019-08-30 14:12
閱讀 681·2019-08-30 12:58
閱讀 3389·2019-08-29 15:19
閱讀 2025·2019-08-29 13:59