REST API最佳實踐

ShevaKuilin 發布于2019-08-16 10:48 / 2306人閱讀

摘要：最佳實踐漸漸成為向外曝露服務的通用方式。有效的使用狀態碼定義了非常多的狀態碼，這些碼對客戶端非常有意義。下面是狀態碼的列表和摘要表示對應的或操作成功。

REST API最佳實踐

REST漸漸成為向外曝露服務的通用方式。之所以這么流行的原因主要是簡單，易于使用，使用HTTP協議（REST可以用于所有協議，但應用最廣泛的是HTTP）等。但是所有向外暴露的資源都被認為是REST是一種誤解，是不正確的。在這里，我會向你介紹一些在你實現自己的REST API時你應該謹記的最佳實踐。

擴展閱讀：REST vs SOAP

下面是一個導讀列表

1.名詞，不要用動詞

2.使用復數

3.文檔

4.接口版本

5.分頁

6.使用SSL

7.HTTP方法

8.有效的使用HTTP狀態碼

1.名詞，不要動詞

REST API開發人員的一個不好的習慣是使用動詞來命名REST接口。你應該使用名詞來替代動詞。

場景

要新建一個REST web services用來獲取印度的農民數據。同時，該接口也可以獲取其他的信息比如收入，農作物名稱，地址等和農民相關的數據。每一個農民都指派了unique ID。
同樣的，服務也需要提供農民關聯的農作物的信息的接口。

最佳實踐

為所有的操作提供單一的endpoint.在下面的例子中，我們為所有的操作（get,add,update,delete）提供了一個endpoint "/farmers",通過不同的HTTP method 來調用不同的操作，下面還會詳細介紹。

/farmers

/crops

盡量避免

盡量避免在命名中使用動詞。推薦在數據中或者HTTP method提現操作。不要像下面這樣命名REST

/getFarmers

/updateFarmers

/deleteFarmers

2.使用復數

使用復數來命名REST服務。這是在REST設計者討論中的熱門話題。

最佳實踐

/farmers

/farmers/{farmer_id}

盡量避免

/farmer

/farmer/{farmer_id}

注意

在實踐中不要混用單數或者復數命名，雖然我說使用復數是最佳實踐，但是如果你堅持使用單數，那么就在所有的服務上執行相同的策略。

3.文檔

對軟件實現文檔化是非常好的習慣，對REST API也是同樣。如果你寫下了有用的文檔，這將使其他開發者收益。對于REST API的常見注釋，主要是列出API的endpoints，對每一個endpoint描述其支持的功能列表。有很多工具可以自動完成這件事情。這些工具有：DRF DOCs,Swagger,Apiary

4.接口版本

任何軟件都會進化，對于API的每一個比較大的變動，可能需要不同的版本號。如果對API版本化，是REST開發者社區的熱門話題。一般來說，有兩種方法來將接口版本化

URI 版本化

使用URI的簡單例子是

http://host/v2/farmers

http://host/v1/farmers
主要的缺點有

破壞了存在的URI，所有的客戶端需要跟著改

增加了需要管理的URI，這會導致增加客戶端保存多個URI版本的緩存增加。會降低緩存的命中率，也會降低應用的運行效率。

非常不具彈性，不能簡單的修改單個資源或者資源的子集。

媒體類型版本化

這個方法是通過在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傳輸的不同版本的請求緩存的復雜度也大大上升了。簡單的說，當客戶端基于URI做緩存，這是簡單的，但是通過媒體類型來緩存就增加了復雜性。

5.分頁

通過HTTP發送大量數據是一個糟糕的做法。這會引發性能問題，因為序列化大的json對象非常耗時耗資源。建議將結果分頁并提供前后的導航鏈接。
如果你在應用中使用分頁，一個較好的做法是使用Link HTTP header option. 這篇文章 link from GitHub應該有用。會幫你打開思路。

6.使用SSL

使用SSL是必須的。REST API必須得到SSL的保護。引用在因特網上發布，無法保證安全的接入。隨著越來越多的計算機犯罪事件，我們必須以正確的方式來保護我們的應用。
API的安全已經有成熟的工業標準。不要使用簡單的認證機制。可以使用Oauth1.0a或者Oauth2來使接口變得安全。建議使用最新的Oauth2。

7.HTTP方法

當你知道各個HTTP方法所扮演的角色后，將操作映射到HTTP的方法是非常簡單的。在前面提及要使用HTTP方法來表示資源的操作，而不是通過不同的服務名字。本節會大致介紹各個HTTP方法的行為模式。
下面兩點是在使用HTTP方法前需要考慮的兩個方面：

安全：當調用方法時不會改變資源的狀態，就認為該HTTP方法時安全的。比如，當通過GET方法獲取數據，因為不會修改數據，所以這個方法就是安全的。

冪等：調用資源多次，所獲得的回應是相同的，這就是冪等。比如，當你嘗試更新數據，每次的返回都相同。
不是所有的方法都是安全和冪等的。下面是一個可以用在REST API調用的列表，表示各個方法安全和冪等的情況

GET          安全        冪等
POST         不安全      不冪等
PUT          不安全      冪等
DELETE       不安全      冪等
OPTIONS      安全        冪等
HEAD         安全        冪等

下面是各個方法的簡要說明，在使用的時候請參考：

GET:這個方法是安全且冪等的。常用于獲取數據。

POST:這個方法不安全也不冪等。常用于創建資源。

PUT:這個方法是冪等。常用于更新資源。需要避免使用POST來更新資源。

DELETE:常用語刪除資源，但是這個方法并不是對所有的請求冪等的。

OPTIONS:這個方法不是用來操作資源的。當客戶端不清楚對應的資源有哪些操作時，使用該操作獲得資源的表示。

HEAD:可以用來查詢一個資源。和GET非常想，但是就如在HTTP的規定所解釋的，HEAD方法必須在header中發送請求和獲得回應。

8.有效的使用HTTP狀態碼

HTTP定義了非常多的狀態碼，這些碼對客戶端非常有意義。你的REST API可以有效的使用這些狀態碼來幫助客戶端。下面是狀態碼的列表和摘要：

200 OK - 表示對應的GET,PUT,PATCH 或 DELETE操作成功。也可以用于POST表示沒有創建成功。

201 Created - 表示POST創建成功

204 No Content - 表示一個成功的響應，body為空（比如 delete）

304 Not Modified - HTTP緩存

400 Bad Request - 表示request錯誤，比如body解析出錯

401 Unauthorized - 提供了錯誤的認證信息。可以在這個錯誤之后觸發認證功能。

403 Forbidden - 當認證成功，但是對應的用戶沒有對應資源的權限時。

404 Not Found - 表示請求一個并不存在的資源

405 Method Not Allowed - 一個認證的用戶，調用了他所不允許使用的方法時。

410 Gone - 表示資源已經不可用。比如調用了一個老的API版本。

415 Unsupported Media Type - request提供了錯誤的content type

422 Unprocessable Entity - 驗證錯誤

429 Too Many Requests - 因為負載限制，拒絕request時。

GPU云服務器云服務器 api設計的最佳實踐最佳實踐 webrtc最佳實踐 cdn最佳實踐

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://m.specialneedsforspecialkids.com/yun/70479.html

編寫 Node.js Rest API 的 10 個最佳實踐

摘要：要對進行黑盒測試測試的最好辦法是對他們進行黑盒測試，黑盒測試是一種不關心應用內部結構和工作原理的測試方法，測試時系統任何部分都不應該被。此外，有了黑盒測試并不意味著不需要單元測試，針對的單元測試還是需要編寫的。本文首發于之乎專欄前端周刊，全文共 6953 字，讀完需 8 分鐘，速度需 2 分鐘。翻譯自：RingStack 的文章 https://blog.risingstack.co...

ermaoL 2019-08-20 14:43 評論0 收藏0
PHP / Laravel API 開發推薦閱讀清單

showImg(https://segmentfault.com/img/bV6aHV?w=1280&h=800); 社區優秀文章 Laravel 5.5+passport 放棄 dingo 開發 API 實戰，讓 API 開發更省心 - 自造車輪。 API 文檔神器 Swagger 介紹及在 PHP 項目中使用 - API 文檔撰寫方案推薦 Laravel API 項目必須使用的 8 個...

shmily 2019-06-28 18:34 評論0 收藏0
現代后端開發者必備技能-2018版

摘要：現在開始創建一個包并分發給其他人使用，并確保遵循你迄今為止學到的標準和最佳實踐。第步實踐對于練習，繼續編寫單元測試，以完成目前為止所做的實際任務，特別是你在步驟中所做的練習。今天的Web開發與幾年前完全不同，有很多不同的東西可以很容易地阻止任何人進入Web開發。這是我們決定制作這些循序漸進的視覺指南的原因之一，這些指南展示了更大的圖景，并讓任何人清楚了解他們在網頁開發中扮演的角色。 ...

eternalshallow 2019-07-01 12:27 評論0 收藏0
2018最新后端開發人員的路線圖

摘要：簡評之前，后端開發路線圖僅僅是一個技術推薦，且沒有明確的方向指明應該遵循的順序，這份重新制作的指南將會給你一個更好的方向。現在開始創建一個包并分發給其他人使用，并確保遵循迄今為止學到的標準和最佳實踐。簡評：之前，后端開發路線圖僅僅是一個技術推薦，且沒有明確的方向指明應該遵循的順序，這份重新制作的指南將會給你一個更好的方向。現在的 Web 開發與幾年前完全不同了，有很多不同的東西可以...

王陸寬 2019-08-16 12:33 評論0 收藏0
專治前端焦慮的學習方案

摘要：不過今天我希望能夠更進一步，不僅僅再抱怨現狀，而是從我個人的角度來給出一個逐步深入學習生態圈的方案。最后，我還是想提到下對于的好的學習方法就是回顧參照各種各樣的代碼庫，學習人家的用法與實踐。本文翻譯自A-Study-Plan-To-Cure-JavaScript-Fatigue。筆者看到里面的幾張配圖著實漂亮，順手翻譯了一波。本文從屬于筆者的Web Frontend Introduc...

codeGoogle 2019-08-21 14:41 評論0 收藏0