全棧開發必備技能：構建RESTful API的13種最佳實踐

首發於公衆號《前端全棧開發者》，第一時間閱讀最新文章，會優先兩天發表新文章。

Facebook、GitHub、Google以及其餘許多巨頭都須要一種服務和消費數據的方式。在當今的開發環境中，RESTful API仍然是服務和消費數據的最佳選擇之一。

可是你是否考慮過學習行業標準？設計RESTful API的最佳實踐是什麼？從理論上講，任何人均可以在不到五分鐘的時間內快速啓動數據API——不管是Node.js，Golang仍是Python。

咱們將探討在構建RESTful API時應考慮的13種最佳實踐。但首先，讓咱們快速闡明RESTful API。

什麼是RESTful API？

RESTful API須要知足如下約束才能被稱爲RESTful API。

1. 客戶端-服務器模型：RESTful API遵循客戶端-服務器模型，其中服務器爲數據提供服務，而客戶端鏈接到服務器以使用數據。客戶端和服務器之間的交互是經過HTTP（S）請求進行的，該請求傳輸了請求的數據。
2. 無狀態：更重要的是，RESTful API應該是無狀態的。每一個請求都被視爲獨立請求。服務器不該跟蹤可能影響未來請求結果的任何內部狀態。

3. 統一接口：最後，一致性定義了客戶端和服務器之間的交互方式。RESTful API定義了命名資源的最佳實踐，但定義了容許你修改資源/與之交互的固定HTTP操做。能夠在RESTful API中訪問如下HTTP操做：

   • GET請求：檢索資源
   • POST請求：建立資源或將信息發送到API
   • PUT請求：建立或替換資源
   • PATCH請求：更新現有資源
   • DELETE請求：刪除資源

在對RESTful API的特性有了更深刻的瞭解後，是時候瞭解更多關於RESTful API的最佳實踐了。

本文爲你提供了13種最佳實踐的可行清單。讓咱們來探索！

1.正確使用HTTP方法

咱們已經討論了可用於修改資源的HTTP方法：GET，POST，PUT，PATCH和DELETE。

儘管如此，許多開發人員仍是傾向於濫用GET和POST或PUT和PATCH。一般，咱們看到開發人員使用POST請求來檢索數據。此外，咱們看到開發人員使用PUT請求來替換資源，而他們只想更新該資源的單個字段。

確保使用正確的HTTP方法，由於這將爲使用你的RESTful API的開發人員增長不少混亂。最好是堅持使用預約的準則。

2.命名約定

瞭解RESTful API命名約定將對你有組織地設計API有很大幫助。根據你服務的資源設計一個RESTful API。

例如，你的API管理着做者和書籍（是的，一個經典的例子）。如今，咱們要添加一個新做者或訪問一個ID爲 3 的做者。你能夠設計下面的路由來達到這個目的：

• api.com/addNewAuthor
• api.com/getAuthorByID/3

想象一下，一個API承載了許多資源，每一個資源都有許多屬性。可能的端點列表將變得無窮無盡，並且對用戶不是很友好。因此咱們須要一種更有條理和標準化的方式來設計API端點。

RESTful API最佳實踐描述了端點應以資源名稱開頭，而HTTP操做則描述操做。如今咱們獲得：

• POST api.com/authors
• GET api.com/authors/3

若是咱們想訪問ID爲 3 的做者曾經寫過的全部書籍怎麼辦？對於這種狀況，RESTful API也有解決辦法：

• GET api.com/authors/3/books

最後，若是您要爲ID爲 3 的做者刪除ID爲 5 的書，該怎麼辦？一樣，讓咱們遵循相同的結構化方法來造成如下端點：

• DELETE api.com/authors/3/books/5

簡而言之，利用HTTP操做和資源映射的結構化方式來造成易於理解的端點路徑。這種方法的最大優勢是，每一個開發人員都瞭解RESTful API的設計方式，他們能夠當即使用API，而沒必要閱讀你的每一個端點的文檔。

3.使用複數資源

資源應始終使用其複數形式。爲何？假設你要檢索全部做者。所以，你將調用如下端點：GET api.com/authors。

當你讀取請求時，你沒法判斷API響應是否只包含一個或全部做者。所以，API端點應該使用複數資源。

4.正確使用狀態碼

狀態碼在這裏不僅是爲了好玩，它們有一個明確的目的，狀態碼通知客戶端請求的成功。

最多見的狀態碼類別包括：

• 200（OK）：請求已成功處理並完成。
• 201（Created）：指示成功建立資源。
• 400（Bad Request）：表明客戶端錯誤。也就是說，請求的格式不正確或缺乏請求參數。
• 401（Unauthorized）：未受權，你嘗試訪問你沒有權限的資源。
• 404（Not Found）：請求的資源不存在。
• 500（Internal Server Error）：內部服務器錯誤，服務器在執行請求期間引起異常。

狀態碼的完整列表能夠在Mozilla Developers找到。

5.遵循相同約定

最多見的是，RESTful API提供JSON數據，所以，應遵循camelCase大小寫慣例。可是，不一樣的編程語言使用不一樣的命名約定。

6.如何處理搜索，分頁，過濾和排序

搜索，分頁，過濾和排序等操做並不表明單獨的端點。這些操做能夠經過使用隨API請求提供的查詢參數來完成。

例如，讓咱們檢索按名稱升序排列的全部做者。你的API請求應以下所示：api.com/authors?sort=name_asc。

此外，我想檢索一個名稱爲「 Michiel」的做者。該請求看起來像這樣 api.com/authors?search=Michiel。

幸運的是，許多API項目都帶有內置的搜索、分頁、過濾和排序功能。這將爲你節省不少時間。

7.API版本控制

我不常看到這一點，但這是對你的API進行版本調整的最佳實踐。這是一種有效的方式來向你的用戶傳達重大的變化。

一般，API的版本號包含在API URL中，例如：api.com/v1/authors/3/books。

8.經過HTTP標頭髮送元數據

HTTP標頭容許客戶端隨其請求發送其餘信息。例如，Authorization 標頭一般用於發送身份驗證數據以訪問API。

你能夠在此處找到全部可能的HTTP標頭的完整列表。

9.限速

速率限制是控制每一個客戶端請求數量的一種有趣方法。這些是服務器可能返回的速率限制標頭：

• X-Rate-Limit-Limit：告訴客戶端在指定時間間隔內能夠發送的請求數。
• X-Rate-Limit-Remaining：告訴客戶端在當前時間間隔內仍能夠發送多少個請求。
• X-Rate-Limit-Reset：告訴客戶端速率限制什麼時候重置。

10.有意義的錯誤處理

若是出現問題，請務必向開發人員提供有意義的錯誤消息，這一點很重要。例如，Twilio API返回如下錯誤格式：

{
  "status": 400,
  "message": "Resource books does not exist",
  "code": 24801,
  "more_info": "api.com/docs/errors/24801"
}

在此示例中，服務器返回狀態代碼和人類可讀的消息。此外，還返回內部錯誤代碼，供開發人員查找特定錯誤，這使開發人員能夠快速查找有關該錯誤的更多信息。

11.選擇正確的API框架

存在許多用於不一樣編程語言的框架，選擇一個支持RESTful API最佳作法的框架很是重要。

對於Node.js，後端開發人員喜歡使用Express.js和Koa，而對於Python，Falcon是一個不錯的選擇。

12.文檔化你的API

最後，寫文檔！我不是在開玩笑，這仍然是傳遞你新開發的API知識最簡單的方法之一。

儘管你的API遵循RESTful API列出的全部最佳實踐，但仍然值得你花時間記錄各類元素，好比API處理的資源或應用於服務器的速率限制。

想一想你的其餘開發人員，文檔大大減小了學習API所需的時間。

13.把事情簡單化！

不要讓你的API過於複雜，保持資源簡單。正肯定義你的API處理的不一樣資源，將幫助你在將來避免資源相關的問題。定義你的資源，還要準肯定義它的屬性和資源之間的關係。這樣一來，如何鏈接不一樣的資源就沒有爭議的空間了。

若是您喜歡這篇介紹API最佳實踐的文章，那麼您可能還喜歡從頭開始學習構建RESTful API。