【譯者注】本文是作者在自己的工作經驗中總結出來的RESTful API設計技巧，雖然部分技巧仍有爭議，但總體來說還是有一定的參考價值的。以下是譯文。
簡單說一下代碼重用
記得在Ken Rogers的Medium博客裏曾經見過這麼一句話（原文出自海明威）：
我們都是手藝學徒，沒有人會成爲大師。
在我寫這篇文章的時候，我不禁笑了起來，因爲從這件事情的背後看到了一個偉大的類比，那就是從其他人那裏引用了海明威的話。也就是說，我不需要爲了得到類似的功能和結果而花費精力自己去創建一個與衆不同的東西，上面提到的海明威的話正是代碼重用在文學上的例子。
但是，我在這裏不會寫代碼包的好處，而是更多地提一些我的感受，這些感受會在當前以及未來的項目中積極地得到實現。我還總結了一套API規則和原語，包括了功能和實現細節。
使用API版本控制
如果你要開發一個提供客戶端服務的API，你需要爲最後可能的修改而做好準備。最好的辦法就是通過爲RESTful API提供“版本命名空間”來實現。
我們只需將版本號作爲前綴添加到所有的URL裏即可。
然而，在我研究了其他的API實現之後發現，我喜歡上了這種較短的URL樣式，它把api作爲是子域名的一部分，並從路由中刪除了/api，這樣更短、更簡潔。
跨域資源共享（CORS）
需要重點關注的是，如果你打算在www.myservice.com上託管你的前端站點，而將API放在另外一個不同的子域上，例如api.myservice.com，那麼你需要在後端實現CORS，這樣才能使得AJAX調用不會拋出
這樣的錯誤。
使用複數形式
當你從/posts請求多個帖子的時候，這樣的URL看起來更明瞭：
更多有關混合類型的信息，請看下文：“使用根級別的‘me’端點（URL）”。
避免查詢字符串
查詢字符串的作用是對關係數據庫返回的記錄集做進一步地過濾。
更多信息請看下文：“避免對嵌套路由的操作”。
使用HTTP方法
我們可使用下面這些HTTP方法：
- GET 用於獲取數據。
- POST 用於添加數據。
- PUT 用於更新數據（整個對象）。
- PATCH 用於更新數據（附帶對象的部分信息）。
- DELETE 用於刪除數據。
補充一點，對於修改對象的部分內容的請求來說，我認爲PATCH是減少請求包大小的一個好的方法，並且它也能很好的跟自動提交/自動保存字段配合起來用。
一個很好的例子是Tumblr的“儀表盤設置”屏幕，其中，“服務的用戶體驗”的一些非關鍵性選項可以單獨地編輯和保存，而不需要點最下面的提交按鈕。
對於POST，PUT或PATCH的成功響應消息，應該返回更新後的對象，而不是隻返回一個null。點擊這裏有一篇http1.0和2.0的對比。
有關響應的其他內容，請閱讀下文：“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作爲可更改的用於人類識別的字符串。點擊這裏有一篇http1.0和2.0的對比。
字段校驗錯誤
對於字段的錯誤，可以這樣返回：
操作校驗錯誤
對於返回操作校驗錯誤：
這樣，你的程序的錯誤提取邏輯要當心非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查詢參數）來調試網絡請求。點擊這裏有一篇JWT生成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生成token實戰。
還值得注意的是，存儲在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文件讀取到的，如果讀取錯誤或者文件不存在，則默認值爲
。