Facebook、GitHub、google以及其他許多巨頭都需要一種服務和消費數(shù)據(jù)的方式。在當今的開發(fā)環(huán)境中，RESTful API仍然是服務和消費數(shù)據(jù)的最佳選擇之一。
但是你是否考慮過學習行業(yè)標準？設(shè)計RESTful API的最佳實踐是什么？從理論上講，任何人都可以在不到五分鐘的時間內(nèi)快速啟動數(shù)據(jù)API——無論是Node.js，Golang還是Python。
我們將探討在構(gòu)建RESTful API時應考慮的13種最佳實踐。但首先，讓我們快速闡明RESTful API。
什么是RESTful API？
RESTful API需要滿足以下約束才能被稱為RESTful API。
- 客戶端-服務器模型：RESTful API遵循客戶端-服務器模型，其中服務器為數(shù)據(jù)提供服務，而客戶端連接到服務器以使用數(shù)據(jù)?？蛻舳撕头掌髦g的交互是通過HTTP（S）請求進行的，該請求傳輸了請求的數(shù)據(jù)。
- 無狀態(tài)：更重要的是，RESTful API應該是無狀態(tài)的。每個請求都被視為獨立請求。服務器不應跟蹤可能影響將來請求結(jié)果的任何內(nèi)部狀態(tài)。
- 統(tǒng)一接口：最后，一致性定義了客戶端和服務器之間的交互方式。RESTful API定義了命名資源的最佳實踐，但定義了允許你修改資源/與之交互的固定HTTP操作。可以在RESTful API中訪問以下HTTP操作：GET請求：檢索資源POST請求：創(chuàng)建資源或?qū)⑿畔l(fā)送到APIPUT請求：創(chuàng)建或替換資源PATCH請求：更新現(xiàn)有資源DELETE請求：刪除資源
在對RESTful API的特性有了更深入的了解后，是時候了解更多關(guān)于RESTful API的最佳實踐了。
本文為你提供了13種最佳實踐的可行清單。讓我們來探索！
1.正確使用HTTP方法
我們已經(jīng)討論了可用于修改資源的HTTP方法：GET，POST，PUT，PATCH和DELETE。
盡管如此，許多開發(fā)人員還是傾向于濫用GET和POST或PUT和PATCH。通常，我們看到開發(fā)人員使用POST請求來檢索數(shù)據(jù)。此外，我們看到開發(fā)人員使用PUT請求來替換資源，而他們只想更新該資源的單個字段。
確保使用正確的HTTP方法，因為這將為使用你的RESTful API的開發(fā)人員增加很多混亂。最好是堅持使用預定的準則。
2.命名約定
了解RESTful API命名約定將對你有組織地設(shè)計API有很大幫助。根據(jù)你服務的資源設(shè)計一個RESTful API。
例如，你的API管理著作者和書籍（是的，一個經(jīng)典的例子）?，F(xiàn)在，我們要添加一個新作者或訪問一個ID為 3 的作者。你可以設(shè)計下面的路由來達到這個目的：
- api.com/addNewAuthor
- api.com/getAuthorByID/3
想象一下，一個API承載了許多資源，每個資源都有許多屬性。可能的端點列表將變得無窮無盡，而且對用戶不是很友好。所以我們需要一種更有條理和標準化的方式來設(shè)計API端點。
RESTful API最佳實踐描述了端點應以資源名稱開頭，而HTTP操作則描述操作?，F(xiàn)在我們得到：
- POST api.com/authors
- GET api.com/authors/3
如果我們想訪問ID為 3 的作者曾經(jīng)寫過的所有書籍怎么辦？對于這種情況，RESTful API也有解決辦法：
- GET api.com/authors/3/books
最后，如果您要為ID為 3 的作者刪除ID為 5 的書，該怎么辦？同樣，讓我們遵循相同的結(jié)構(gòu)化方法來形成以下端點：
- DELETE api.com/authors/3/books/5
簡而言之，利用HTTP操作和資源映射的結(jié)構(gòu)化方式來形成易于理解的端點路徑。這種方法的最大優(yōu)點是，每個開發(fā)人員都了解RESTful API的設(shè)計方式，他們可以立即使用API，而不必閱讀你的每個端點的文檔。
3.使用復數(shù)資源
資源應始終使用其復數(shù)形式。為什么？假設(shè)你要檢索所有作者。因此，你將調(diào)用以下端點：GET api.com/authors。
當你讀取請求時，你無法判斷API響應是否只包含一個或所有作者。因此，API端點應該使用復數(shù)資源。
4.正確使用狀態(tài)碼
狀態(tài)碼在這里不只是為了好玩，它們有一個明確的目的，狀態(tài)碼通知客戶端請求的成功。
最常見的狀態(tài)碼類別包括：
- 200（OK）：請求已成功處理并完成。
- 201（Created）：指示成功創(chuàng)建資源。
- 400（Bad Request）：代表客戶端錯誤。也就是說，請求的格式不正確或缺少請求參數(shù)。
- 401（Unauthorized）：未授權(quán)，你嘗試訪問你沒有權(quán)限的資源。
- 404（Not Found）：請求的資源不存在。
- 500（Internal Server Error）：內(nèi)部服務器錯誤，服務器在執(zhí)行請求期間引發(fā)異常。
狀態(tài)碼的完整列表可以在Mozilla Developers找到。
5.遵循相同約定
最常見的是，RESTful API提供JSON數(shù)據(jù)，因此，應遵循camelCase大小寫慣例。但是，不同的編程語言使用不同的命名約定。
6.如何處理搜索，分頁，過濾和排序
搜索，分頁，過濾和排序等操作并不代表單獨的端點。這些操作可以通過使用隨API請求提供的查詢參數(shù)來完成。
例如，讓我們檢索按名稱升序排列的所有作者。你的API請求應如下所示：api.com/authors?sort=name_asc。
此外，我想檢索一個名稱為“ Michiel”的作者。該請求看起來像這樣 api.com/authors?search=Michiel。
幸運的是，許多API項目都帶有內(nèi)置的搜索、分頁、過濾和排序功能。這將為你節(jié)省很多時間。
7.API版本控制
我不常看到這一點，但這是對你的API進行版本調(diào)整的最佳實踐。這是一種有效的方式來向你的用戶傳達重大的變化。
通常，API的版本號包含在API URL中，例如：api.com/v1/authors/3/books。
8.通過HTTP標頭發(fā)送元數(shù)據(jù)
HTTP標頭允許客戶端隨其請求發(fā)送其他信息。例如，Authorization 標頭通常用于發(fā)送身份驗證數(shù)據(jù)以訪問API。
你可以在此處找到所有可能的HTTP標頭的完整列表。
9.限速
速率限制是控制每個客戶端請求數(shù)量的一種有趣方法。這些是服務器可能返回的速率限制標頭：
- X-Rate-Limit-Limit：告訴客戶端在指定時間間隔內(nèi)可以發(fā)送的請求數(shù)。
- X-Rate-Limit-Remaining：告訴客戶端在當前時間間隔內(nèi)仍可以發(fā)送多少個請求。
- X-Rate-Limit-Reset：告訴客戶端速率限制何時重置。
10.有意義的錯誤處理
如果出現(xiàn)問題，請務必向開發(fā)人員提供有意義的錯誤消息，這一點很重要。例如，Twilio API返回以下錯誤格式：
{
"status": 400,
"message": "Resource books does not exist",
"code": 24801,
"more_info": "api.com/docs/errors/24801"
}
在此示例中，服務器返回狀態(tài)代碼和人類可讀的消息。此外，還返回內(nèi)部錯誤代碼，供開發(fā)人員查找特定錯誤，這使開發(fā)人員可以快速查找有關(guān)該錯誤的更多信息。
11.選擇正確的API框架
存在許多用于不同編程語言的框架，選擇一個支持RESTful API最佳做法的框架非常重要。
對于Node.js，后端開發(fā)人員喜歡使用Express.js和Koa，而對于Python，F(xiàn)alcon是一個不錯的選擇。
12.文檔化你的API
最后，寫文檔！我不是在開玩笑，這仍然是傳遞你新開發(fā)的API知識最簡單的方法之一。
盡管你的API遵循RESTful API列出的所有最佳實踐，但仍然值得你花時間記錄各種元素，比如API處理的資源或應用于服務器的速率限制。
想想你的其他開發(fā)人員，文檔大大減少了學習API所需的時間。
13.把事情簡單化！
不要讓你的API過于復雜，保持資源簡單。正確定義你的API處理的不同資源，將幫助你在未來避免資源相關(guān)的問題。定義你的資源，還要準確定義它的屬性和資源之間的關(guān)系。這樣一來，如何連接不同的資源就沒有爭議的空間了。
