API設計技巧參考
簡單說一下代碼重用
記得在Ken Rogers的Medium博客里曾經(jīng)見過這么一句話（原文出自海明威）：
我們都是手藝學徒，沒有人會成為大師。
在我寫這篇文章的時候，我不禁笑了起來，因為從這件事情的背后看到了一個偉大的類比，那就是從其他人那里引用了海明威的話。也就是說，我不需要為了得到類似的功能和結果而花費精力自己去創(chuàng)建一個與眾不同的東西，上面提到的海明威的話正是代碼重用在文學上的例子。
但是，我在這里不會寫代碼包的好處，而是更多地提一些我的感受，這些感受會在當前以及未來的項目中積極地得到實現(xiàn)。我還總結了一套API規(guī)則和原語，包括了功能和實現(xiàn)細節(jié)。
使用API版本控制
如果你要開發(fā)一個提供客戶端服務的API，你需要為最后可能的修改而做好準備。最好的辦法就是通過為RESTful API提供“版本命名空間”來實現(xiàn)。
我們只需將版本號作為前綴添加到所有的URL里即可。
然而，在我研究了其他的API實現(xiàn)之后發(fā)現(xiàn)，我喜歡上了這種較短的URL樣式，它把api作為是子域名的一部分，并從路由中刪除了/api，這樣更短、更簡潔。
跨域資源共享（CORS）
需要重點關注的是，如果你打算在www.myservice.com上托管你的前端站點，而將API放在另外一個不同的子域上，例如api.myservice.com，那么你需要在后端實現(xiàn)CORS，這樣才能使得AJAX調(diào)用不會拋出這樣的錯誤。
使用復數(shù)形式
當你從/posts請求多個帖子的時候，這樣的URL看起來更明了：
更多有關混合類型的信息，請看下文：“使用根級別的‘me’端點（URL）”。
避免查詢字符串
查詢字符串的作用是對關系數(shù)據(jù)庫返回的記錄集做進一步地過濾。
更多信息請看下文：“避免對嵌套路由的操作”。
使用HTTP方法
我們可使用下面這些HTTP方法：
GET 用于獲取數(shù)據(jù)。
POST 用于添加數(shù)據(jù)。
PUT 用于更新數(shù)據(jù)（整個對象）。
PATCH 用于更新數(shù)據(jù)（附帶對象的部分信息）。
DELETE 用于刪除數(shù)據(jù)。
補充一點，對于修改對象的部分內(nèi)容的請求來說，我認為PATCH是減少請求包大小的一個好的方法，并且它也能很好的跟自動提交/自動保存字段配合起來用。
一個很好的例子是Tumblr的“儀表盤設置”屏幕，其中，“服務的用戶體驗”的一些非關鍵性選項可以單獨地編輯和保存，而不需要點最下面的提交按鈕。
對于POST，PUT或PATCH的成功響應消息，應該返回更新后的對象，而不是只返回一個null。
有關響應的其他內(nèi)容，請閱讀下文：“JSON格式的響應和請求”。
使用封包
“我不喜歡數(shù)據(jù)封包。它只是引入了另一個鍵來瀏覽數(shù)據(jù)樹。元信息應該包含在包頭中?！?/p>
最初，我堅持認為封包數(shù)據(jù)是不必要的，HTTP協(xié)議已經(jīng)提供了足夠的“封包”來傳遞響應消息。
然而，根據(jù)Reddit上的回復所述，如果不封包為JSON數(shù)組，則可能會出現(xiàn)各種漏洞和潛在的黑客攻擊。
現(xiàn)在建議使用封包，你應該把數(shù)據(jù)封包后再應答！
同樣要重點關注的是，不像其他語言那樣，Java之類的語言將會將空對象認為是true！ 因此，在下面這種情況下，不要返回空的對象來作為響應的一部分：
JSON格式的響應和請求
所有東西都應該被序列化成JSON。如果你期待從服務器上獲取JSON格式的數(shù)據(jù)，那么請客氣一點，請發(fā)送JSON格式的內(nèi)容給服務器。請兩邊保持一致！
某些情況下，如果動作執(zhí)行成功（例如DELETE），那我并沒有什么需要返回的。但是，在某些語言（如Python）中返回一個空對象可能被認為是false，并且在開發(fā)人員調(diào)試程序的時候，這種情況并不容易發(fā)現(xiàn)。因此，我喜歡返回“OK”，盡管這是一個字符串，但是在返回的時候會被包裝成一個簡單的響應對象。
使用HTTP狀態(tài)碼和錯誤響應
因為我們使用了HTTP方法，所以我們應當使用HTTP狀態(tài)碼。
我喜歡使用這些狀態(tài)碼：
對于數(shù)據(jù)錯誤
400：請求信息不完整或無法解析。
422：請求信息完整，但無效。
404：資源不存在。
409：資源沖突。
對于鑒權錯誤
401：訪問令牌沒有提供，或者無效。
403：訪問令牌有效，但沒有權限。
對于標準狀態(tài)
200： 所有的都正確。
500： 服務器內(nèi)部拋出錯誤。
假設要創(chuàng)建一個新帳戶，我們提供了email和password兩個值。我們希望讓客戶端應用程序能夠阻止任何無效的電子郵件或密碼太短的請求，但外部人員可以像我們的客戶端應用程序一樣在需要的時候直接訪問API。
如果email字段丟失，則返回400。
如果password字段太短，則返回422。
如果email字段不是有效的電子郵件，則返回422。
如果email已經(jīng)被使用，返回一個409。
從上面這些情況來看，有兩個錯誤會返回422，不過他們的原因是不同的。這就是為什么我們需要一個錯誤碼，甚至是一個錯誤描述。要區(qū)分代碼和描述，我打算將error（代碼）作為機器可識別的常量，將deion作為可更改的用于人類識別的字符串。
非常好我支持^.^
(0) 0%
不好我反對
(0) 0%