Restful Api 接口風格，最佳實踐設計

RESTful API的開發和使用，無非是客戶端向服務器發請求（request），以及服務器對客戶端請求的響應（response）。具備統一接口的特色，即，使用不一樣的http方法表達不一樣的行爲：

• GET（SELECT）：從服務器取出資源（一項或多項）
• POST（CREATE）：在服務器新建一個資源
• PUT（UPDATE）：在服務器更新資源（客戶端提供完整資源數據）
• PATCH（UPDATE）：在服務器更新資源（客戶端提供須要修改的資源數據）
• DELETE（DELETE）：從服務器刪除資源
• GET /tickets # 獲取ticket列表
• GET /tickets/12 # 查看某個具體的ticket
• POST /tickets # 新建一個ticket
• PUT /tickets/12 # 更新ticket 12.
• DELETE /tickets/12 #刪除ticekt 12

經常使用的Response要包含的數據和狀態碼（status code），不完善的內容，歡迎你們補充:

• 當GET, PUT和PATCH請求成功時，要返回對應的數據，及狀態碼200，即SUCCESS
• 當POST建立數據成功時，要返回建立的數據，及狀態碼201，即CREATED
• 當DELETE刪除數據成功時，不返回數據，狀態碼要返回204，即NO CONTENT
• 當GET 不到數據時，狀態碼要返回404，即NOT FOUND
• 任什麼時候候，若是請求有問題，如校驗請求數據時發現錯誤，要返回狀態碼 400，即BAD REQUEST
• 當API 請求須要用戶認證時，若是request中的認證信息不正確，要返回狀態碼 401，即NOT AUTHORIZED
• 當API 請求須要驗證用戶權限時，若是當前用戶無相應權限，要返回狀態碼 403，即FORBIDDEN

 最後，關於Request 和 Response，不要忽略了http header中的Content-Type。以json爲例，若是API要求客戶端發送request時要傳入json數據，則服務器端僅作好json數據的獲取和解析便可，但若是服務端支持多種類型數據的傳入，如同時支持json和form-data，則要根據客戶端發送請求時header中的Content-Type，對不一樣類型是數據分別實現獲取和解析；若是API響應客戶端請求後，須要返回json數據，須要在header中添加Content-Type=application/json。

使用方式

GET http://www.birjemin.com/api/user # 獲取列表

POST http://www.birjemin.com/api/user # 建立用戶

PUT http://www.birjemin.com/api/user/{id} # 修改用戶信息

DELETE http://www.birjemin.com/api/user/{id} # 刪除用戶信息

設計要素

• 資源路徑： /users , /articles
• HTTP動詞： GET,POST,DELETE,PUT
• 過濾信息： 文章分頁篩選
• 狀態碼： 200，404，422，403…
• 錯誤處理：輸出JSON格式錯誤信息
• 返回結果：輸出JSON數組或JSON對象
• version，必須向前兼容，版本號可放入head（有時把版本號放在URL裏要比放在請求的首部中更容易實現和使用）

 

速度限制
若是對訪問的次數不加控制，極可能會形成 API 被濫用，甚至被 DDos 攻擊。根據使用者不一樣的身份對其進行限流，能夠防止這些狀況，減小服務器的壓力。爲此 RFC 6585 引入了HTTP狀態碼429（too many requests）。加入速度設置以後，應該提示用戶，至於如何提示標準上沒有說明，不過流行的方法是使用HTTP的返回頭。

對用戶的請求限流以後，要有方法告訴用戶它的請求使用狀況，Github API 使用的三個相關的頭部：

X-RateLimit-Limit: 用戶每一個小時容許發送請求的最大值
X-RateLimit-Remaining：當前時間窗口剩下的可用請求數目
X-RateLimit-Rest: 時間窗口重置的時候，到這個時間點可用的請求數量就會變成X-RateLimit-Limit的值
若是容許沒有登陸的用戶使用 API（可讓用戶試用），能夠把 X-RateLimit-Limit 的值設置得很小，好比 Github 使用的 60。沒有登陸的用戶是按照請求的 IP 來肯定的，而登陸的用戶按照認證後的信息來肯定身份。

對於超過流量的請求，能夠返回429 Too many requests狀態碼，並附帶錯誤信息。而 Github API 返回的是403 Forbidden，雖然沒有 429 更準確，也是能夠理解的。

宗旨：

漂亮、簡潔、優雅