RESTful API設計技巧經驗總結

作者 | Peter Boyer

翻譯 | 雁驚寒

【譯者注】本文是作者在自己的工作經驗中總結出來的RESTful API設計技巧，雖然部分技巧仍有爭議，但總體來說還是有一定的參考價值的。以下是譯文。

簡單說一下代碼重用

記得在Ken Rogers的Medium博客里曾經見過這麼一句話（原文出自海明威）：

我們都是手藝學徒，沒有人會成為大師。

在我寫這篇文章的時候，我不禁笑了起來，因為從這件事情的背後看到了一個偉大的類比，那就是從其他人那裡引用了海明威的話。也就是說，我不需要為了得到類似的功能和結果而花費精力自己去創建一個與眾不同的東西，上面提到的海明威的話正是代碼重用在文學上的例子。

但是，我在這裡不會寫代碼包的好處，而是更多地提一些我的感受，這些感受會在當前以及未來的項目中積極地得到實現。我還總結了一套API規則和原語，包括了功能和實現細節。

使用API版本控制

如果你要開發一個提供客戶端服務的API，你需要為最後可能的修改而做好準備。最好的辦法就是通過為RESTful API提供「版本命名空間」來實現。

我們只需將版本號作為前綴添加到所有的URL里即可。

然而，在我研究了其他的API實現之後發現，我喜歡上了這種較短的URL樣式，它把api作為是子域名的一部分，並從路由中刪除了/api，這樣更短、更簡潔。

跨域資源共享（CORS）

使用複數形式

當你從/posts請求多個帖子的時候，這樣的URL看起來更明了：

更多有關混合類型的信息，請看下文：「使用根級別的『me』端點（URL）」。

避免查詢字元串

查詢字元串的作用是對關係資料庫返回的記錄集做進一步地過濾。

更多信息請看下文：「避免對嵌套路由的操作」。

使用HTTP方法

我們可使用下面這些HTTP方法：

GET 用於獲取數據。

POST 用於添加數據。

PUT 用於更新數據（整個對象）。

PATCH 用於更新數據（附帶對象的部分信息）。

DELETE 用於刪除數據。

補充一點，對於修改對象的部分內容的請求來說，我認為PATCH是減少請求包大小的一個好的方法，並且它也能很好的跟自動提交/自動保存欄位配合起來用。

一個很好的例子是Tumblr的「儀錶盤設置」屏幕，其中，「服務的用戶體驗」的一些非關鍵性選項可以單獨地編輯和保存，而不需要點最下面的提交按鈕。

對於POST，PUT或PATCH的成功響應消息，應該返回更新後的對象，而不是只返回一個null。

有關響應的其他內容，請閱讀下文：「JSON格式的響應和請求」。

使用封包

「我不喜歡數據封包。它只是引入了另一個鍵來瀏覽數據樹。元信息應該包含在包頭中。」

最初，我堅持認為封包數據是不必要的，HTTP協議已經提供了足夠的「封包」來傳遞響應消息。

然而，根據Reddit上的回復所述，如果不封包為JSON數組，則可能會出現各種漏洞和潛在的黑客攻擊。

現在建議使用封包，你應該把數據封包後再應答！

同樣要重點關注的是，不像其他語言那樣，JavaScript之類的語言將會將空對象認為是true！ 因此，在下面這種情況下，不要返回空的對象來作為響應的一部分：

JSON格式的響應和請求

所有東西都應該被序列化成JSON。如果你期待從伺服器上獲取JSON格式的數據，那麼請客氣一點，請發送JSON格式的內容給伺服器。請兩邊保持一致！

某些情況下，如果動作執行成功（例如DELETE），那我並沒有什麼需要返回的。但是，在某些語言（如Python）中返回一個空對象可能被認為是false，並且在開發人員調試程序的時候，這種情況並不容易發現。因此，我喜歡返回「OK」，儘管這是一個字元串，但是在返回的時候會被包裝成一個簡單的響應對象。

使用HTTP狀態碼和錯誤響應

因為我們使用了HTTP方法，所以我們應當使用HTTP狀態碼。

我喜歡使用這些狀態碼：

對於數據錯誤

400：請求信息不完整或無法解析。

422：請求信息完整，但無效。

404：資源不存在。

409：資源衝突。

對於鑒權錯誤

401：訪問令牌沒有提供，或者無效。

403：訪問令牌有效，但沒有許可權。

對於標準狀態

200： 所有的都正確。

500： 伺服器內部拋出錯誤。

假設要創建一個新帳戶，我們提供了email和password兩個值。我們希望讓客戶端應用程序能夠阻止任何無效的電子郵件或密碼太短的請求，但外部人員可以像我們的客戶端應用程序一樣在需要的時候直接訪問API。

如果email欄位丟失，則返回400。

如果password欄位太短，則返回422。

如果email欄位不是有效的電子郵件，則返回422。

如果email已經被使用，返回一個409。

從上面這些情況來看，有兩個錯誤會返回422，不過他們的原因是不同的。這就是為什麼我們需要一個錯誤碼，甚至是一個錯誤描述。要區分代碼和描述，我打算將error（代碼）作為機器可識別的常量，將description作為可更改的用於人類識別的字元串。

欄位校驗錯誤

對於欄位的錯誤，可以這樣返回：

操作校驗錯誤

對於返回操作校驗錯誤：

這樣，你的程序的錯誤提取邏輯要當心非200的錯誤了，你可以直接從響應中檢查error欄位，然後將其與客戶端中相應的邏輯進行比較。

status這個欄位似乎也很有用，如果你不想檢查響應里的元數據，那你可以在需要的時候有條件地添加這個欄位。

description可作為備用的用戶可讀的錯誤消息。

密碼規則

在做了很多密碼規則的研究之後，我比較贊同《密碼規則是廢話》（https://blog.codinghorror.com/password-rules-are-bullshit/）和《NIST禁止做的事情》（https://nakedsecurity.sophos.com/2016/08/18/nists-new-password-rules-what-you-need-to-know/）這兩篇帖子的觀點。

整理了一些處理密碼的規則：

1. 執行unicode密碼的最小長度策略（最小8-10位）。

2. 檢查常見的密碼（例如「password12345」）

3. 檢查密碼熵（不允許使用「aaaaaaaaaaaaa」）。

4. 不要使用密碼編寫規則（至少包含其中一個字元「！@＃$％＆」）。

5. 不要使用密碼提示（「assword」這樣的）。

6. 不要使用基於知識的認證。

7. 不要超期不修改密碼。

8. 不要使用簡訊進行雙認證。

9. 使用32位以上的密碼鹽（salt）。

在某種程度上，所有這些規則能使密碼驗證更容易！

使用訪問和刷新令牌

現代的無狀態、RESTful API一般會使用令牌來實現身份認證。這消除了在無狀態伺服器上處理會話和Cookie的需要，並且可以很容易地使用Authorization頭（或access_token查詢參數）來調試網路請求。

訪問令牌用於認證所有未來的API請求，生命期短，不會被取消。

刷新令牌在初始登錄的響應中返回，然後跟過期時間戳和與使用者的關係一起進行散列計算後存儲到資料庫中。這個長生命期的像密碼一樣的密鑰，可以被用來請求新的短生命期的JWT訪問令牌。刷新令牌也可以用於續訂並延長其使用壽命，這意味著如果用戶持續使用該服務，則無需再次登錄。

但是，如果API希望簽訂一個不同的「密鑰」，JWT就會被取消，但是這將使所有當前發出的令牌全部無效，但因為這些令牌是短生命期的，所以這並沒有關係。

登錄

在我的程序實現中，正常的登錄過程如下所示：

1. 通過/login接收郵件和密碼。

2. 檢查資料庫的電子郵件和密碼哈希。

3. 創建一個新的刷新令牌和JWT訪問令牌。

4. 返回以上兩個數據。

續訂令牌

正常的續訂驗證流程如下所示：

1. 嘗試從客戶端創建請求時，JWT已經過期。

2. 將刷新令牌提交到/renew。

3. 通過將刷新令牌進行哈希與資料庫中保存的進行匹配。

4. 成功後，創建新的JWT訪問令牌並延長到期時間。

5. 返回訪問令牌。

驗證令牌

通過檢查到期日期和簽名哈希可以校驗JWT訪問令牌的有效性。如果校驗失敗，則認為是一個無效的令牌。

如果驗證通過，則JWT的有效載荷中包含了一個uid，它用於在API響應的上下文中傳遞一個對應的user對象來檢查許可權/角色，並相應地創建/讀取/更新/刪除數據。

終止會話

由於刷新令牌存儲在資料庫中，因此可以將其刪除來「終止會話」。這為用戶提供了一個控制方法，即他們可以通過主動的刷新令牌「會話」來保護自己的帳戶，並且通過這種方法來進行多次重複認證（通過調整超時時間戳來實現）。

讓JWT保持小巧

在把信息序列化到JWT訪問令牌中時，請儘可能地讓這個信息小巧，身份驗證令牌的生命期不需要很長，因此沒必要。如果可以的話，只序列化用戶的uid（id）就可以了，其餘的可以通過「GET /me」來傳遞。

還值得注意的是，存儲在JWT有效載荷中的任何敏感信息並不安全，因為它只是一個經過base64編碼的字元串。

使用根級別的「Me」端點（URL）

一般人會使用/profile這個URL來提供自身的基本屬性。但是，我也看到過比較混論的實現，例如對於/users/:id這種接受整數的URL，它竟然允許傳入字元串me來指向自身的屬性。

通過/me訪問自身信息的更深層次的URL，例如/me的/settings或者/billing信息，而通過users/:id/billing訪問其他用戶的信息。

避免對嵌套路由的操作

有一個採用了以上一些設計理念的重構的項目，最後卻設計出了一個難用的URL系統：

如果要POST上傳一個附件，這個URL可能看起來還行，但是如果在開發客戶端應用程序時想要實現像對附件標星號這麼一個簡單操作的功能的話，那你就需要重寫相關的代碼。相關代碼如下：

attachments.js

助手函數的代碼如下：

MyComponent.js

如果你把獲取附件屬性這個功能委派給伺服器來實現，並且只使用根級別的URL，這樣不是更好嗎？

attachments.js

MyComponent.js

總的來說，我認為這兩種方法各有各的優勢，而我傾向於用一個長的路徑來創建/提取資源，用一個短的路徑來更新/刪除資源。

提供分頁功能

分頁很重要，因為你不會想讓一個簡單的請求就獲得數千行的記錄。這個問題似乎很明顯，但是還是會有許多人忽略這個功能。

有多種方法來實現分頁：

「From」參數

可以說這是最容易實現的，API接受一個from查詢字元串參數，然後從這個偏移量開始返回有限數量的結果（通常返回20個結果）。

另外最好提供一個limit參數來限制最大記錄數，例如Twitter，最大限制為1000，而默認限制為200。

「下一頁」令牌

如果每頁20個結果之外還有其他的結果，谷歌的Places API就會在響應中返回next_page_token。然後，伺服器在新的請求中接收到這個令牌後，就會返回更多的結果，並附帶新的next_page_token，直到所有的結果全部都返回給客戶端。

Twitter使用參數next_cursor實現了類似的功能。

實現「健康檢查」URL

很有必要提供一種方法來輸出一個簡單的響應，以此來表明API實例是活著的，不需要重新啟動。這個功能也很有用，通過它可以很方便地檢查某個時間點的某台伺服器上的API是什麼版本，而這無需通過認證。

我提供了status和version這兩個值。另外值得一提的是，這個值是從version.txt文件讀取到的，如果讀取錯誤或者文件不存在，則默認值為。

點擊展開全文

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！