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