構建RESTful API的13種最佳實踐

翻譯：Eolinker
來源：www.eolinker.com
Facebook、GitHub、Google以及其他許多巨頭都需要一種服務和消費資料的方式，在當今的開發環境中，RESTful API仍然是服務和消費資料的最佳選擇之一，
但是你是否考慮過學習行業標準？設計RESTful API的最佳實踐是什么？從理論上講，任何人都可以在不到五分鐘的時間內快速啟動資料API——無論是Node.js，Golang還是Python，
我們將探討在構建RESTful API時應考慮的13種最佳實踐，

什么是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[1]找到，

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，
你可以在此處[2]找到所有可能的HTTP標頭的完整串列，

9.限速
速率限制是控制每個客戶端請求數量的一種有趣方法，這些是服務器可能回傳的速率限制標頭：
? X-Rate-Limit-Limit：告訴客戶端在指定時間間隔內可以發送的請求數，
? X-Rate-Limit-Remaining：告訴客戶端在當前時間間隔內仍可以發送多少個請求，
? X-Rate-Limit-Reset：告訴客戶端速率限制何時重置，
?
10.有意義的錯誤處理
如果出現問題，請務必向開發人員提供有意義的錯誤訊息，這一點很重要，例如，Twilio API回傳以下錯誤格式：

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

11.選擇正確的API框架
存在許多用于不同編程語言的框架，選擇一個支持RESTful API最佳做法的框架非常重要，
對于Node.js，后端開發人員喜歡使用Express.js和Koa，而對于Python，Falcon是一個不錯的選擇，

12.檔案化你的API
最后，寫檔案！我不是在開玩笑，這仍然是傳遞你新開發的API知識最簡單的方法之一，
盡管你的API遵循RESTful API列出的所有最佳實踐，但仍然值得你花時間記錄各種元素，比如API處理的資源或應用于服務器的速率限制，
想想你的其他開發人員，檔案大大減少了學習API所需的時間，

13.把事情簡單化！
不要讓你的API過于復雜，保持資源簡單，正確定義你的API處理的不同資源，將幫助你在未來避免資源相關的問題，定義你的資源，還要準確定義它的屬性和資源之間的關系，這樣一來，如何連接不同的資源就沒有爭議的空間了，

標籤：其他

上一篇：關于API微服務網關

下一篇：軟體測驗算吃青春飯的嗎?