本文不求完全細緻，只求看到這些東西的時候還能想起來那麼一回事
本文內容部分摘自網絡，主要參考阮一峯老師的文章
- API的關鍵要求:
- 當標準合理的時候遵守標準。
- API應該對程序員友好，並且在瀏覽器地址欄容易輸入。
- API應該簡單，直觀，容易使用的同時優雅。
- API應該具有足夠的靈活性來支持上層ui。
- API設計權衡上述幾個原則。
- 使用RESTful URLs 和action.
- 即 將API在邏輯上區分爲資源.並且能夠通過http的
get,post,put,delete來進行操作.
- 即 將API在邏輯上區分爲資源.並且能夠通過http的
- 如何拆分這些資源呢?
- 這裏的關鍵是隱藏內部資源，暴露必需的外部資源。
- 一旦定義好了要暴露的資源，你可以定義資源上允許的操作，以及這些操作和你的API的對應關係：
GET /tickets# 獲取ticket列表
GET /tickets/12# 查看某個具體的ticket
POST /tickets# 新建一個ticket
PUT /tickets/12# 更新ticket 12.
DELETE /tickets/12#刪除ticekt 12
可以看出使用REST的好處在於可以充分利用http的強大實現對資源的CURD功能
使用複數還是單數
雖然看起來使用複數來描述某一個資源實例看起來彆扭，但是統一所有的endpoint，使用複數使得你的URL更加規整。
如何處理關聯？關於如何處理資源之間的管理REST原則也有相關的描述：
GET /tickets/12/messages- Retrieves list of messages for ticket #12
GET /tickets/12/messages/5- Retrieves message #5 for ticket #12
POST /tickets/12/messages- Creates a new message in ticket #12
PUT /tickets/12/messages/5- Updates message #5 for ticket #12
PATCH /tickets/12/messages/5- Partially updates message #5 for ticket #12
DELETE /tickets/12/messages/5- Deletes message #5 for ticket #12
- 不符合CRUD的操作.
重構你的行爲action。當你的行爲不需要參數的時候，你可以把active對應到activated這個資源，（更新使用patch）.
以子資源對待。例如:github上，對一個gists加星操作：PUT /gists/:id/star並且取消星操作：DELETE /gists/:id/star.
有時候action實在沒有難以和某個資源對應上例如search。那就這麼辦吧。我認爲API的使用者對於/search這種url也不會有太大意見的（畢竟他很容易理解）。只要注意在文檔中寫清楚就可以了。 - 安全性
OAuth 2 認證. 文檔
版本化
對外公開的API要兼容以前版本的內容.- 結果過濾,排序,搜索
這些都應該通過參數實現. - 限制API返回值的域
API使用者可能並不需要所有的結果,可以提供一個fileds字段來區分使用者要返回哪些字段. - 更新和創建操作應該返回資源
更新完成或者創建完成後,應該返回對應的資源. - 是否需要 “HATEOAS“
有待研究 - 只提供json作爲返回格式
- 如果使用json最好遵循JavaScript的命名方法.使用駝峯命名法
- 默認使用
pretty print格式，使用gzip
fastjson只能通過toJsonString方法在將對象轉化爲json樣式的字符串時有一個prettyFormatter參數. - 只在需要的時候使用“envelope”
{
"data" : {
"id" : 123,
"name" : "John"
}
}
- 在post,put,patch上使用json作爲輸入
在請求頭中加入Content-Type：application/json - 分頁
- 自動加載相關的資源
可以再url參數中追加一個embed或者expend,表示要自動加載的相關資源. 注意不要產生N+1 select的問題 - 重寫HTTP方法
- 速度限制
- 爲什麼使用當前時間段剩餘秒數而不是時間戳？
- 鑑權 Authentication和安全性衝突了吧
緩存
HTTP提供了自帶的緩存框架。你需要做的是在返回的時候加入一些返回頭信息，在接受輸入的時候加入輸入驗證。基本兩種方法：
ETag：當生成請求的時候，在HTTP頭裏面加入ETag，其中包含請求的校驗和和哈希值，這個值和在輸入變化的時候也應該變化。如果輸入的HTTP請求包含IF-NONE-MATCH頭以及一個ETag值，那麼API應該返回304 not modified狀態碼，而不是常規的輸出結果。Last-Modified：和etag一樣，只是多了一個時間戳。返回頭裏的Last-Modified：包含了 RFC 1123 時間戳，它和IF-MODIFIED-SINCE一致。HTTP規範裏面有三種date格式，服務器應該都能處理。
出錯處理
api應該返回刻度的錯誤信息,至少要將400系列的錯誤信息以json格式返回.- HTTP 狀態碼
