restFul介紹及其使用規範

什麼是REST和RESTful API？

　　REST：（英文：Representational State Transfer，簡稱REST）表徵性狀態轉移，是一種軟件架構風格。

　　RESTful ： RESTful API就是REST風格的API

restFul規範：
　　一、建議使用https做爲網絡通訊協議
　　二、接口的url建議加上'api'字符，清晰地代表此url是一個接口
　　三、接口版本號相關字符v1/v2/v3...建議加在接口的url上，代表當前接口的版本號
　　四、返回值中包含狀態碼或者Code，狀態碼標識當前http請求的響應碼，響應碼具體代表的狀態在http協議裏已經作了解釋。而code則是對請求返回狀態的更細的細分，code彌補了狀態碼不夠用的現實，具體的code代表哪一種狀態，咱們須要跟前端商量決定。
　　　　經常使用狀態碼：
　　　　200 OK - [GET]：服務器成功返回用戶請求的數據，該操做是冪等的（Idempotent）。
　　　　201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
　　　　202 Accepted - [*]：表示一個請求已經進入後臺排隊（異步任務）
　　　　204 NO CONTENT - [DELETE]：用戶刪除數據成功。
　　　　400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操做，該操做是冪等的。
　　　　401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。
　　　　403 Forbidden - [*] 表示用戶獲得受權（與401錯誤相對），可是訪問是被禁止的。
　　　　404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操做，該操做是冪等的。
　　　　406 Not Acceptable - [GET]：用戶請求的格式不可得（好比用戶請求JSON格式，可是隻有XML格式）。
　　　　410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再獲得的。
　　　　422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個對象時，發生一個驗證錯誤。
　　　　500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將沒法判斷髮出的請求是否成功。
　　五、路徑，把網路上的任何東西都看做資源，restful協議建議咱們使用名詞來代表接口url路徑path
　　　　https://www.luffycity.com/api/v1/animals
　　六、method：請求方法，restful建議操做同一資源根據不一樣的http請求方法執行增刪改查等不一樣的操做
　　　　GET：從服務器取出資源
　　　　POST：建立新的資源
　　　　PUT：更新資源的所有屬性字段
　　　　PATCH：更新資源的局部屬性字段
　　　　DELETE：從服務器上刪除資源
　　七、過濾篩選，restful建議咱們把操做資源時的過濾條件加在url上面，多以查詢字符串的方式
　　　　https://www.luffycity.com/api/v1/animals?age=10&gender=0

　　八、錯誤處理，當返回值的狀態碼爲4XX時，返回錯誤信息，以便前端展現
　　　　return HttpResponse({'detail': '用戶名或者密碼錯誤'},  status=400)

　　九、返回結果，針對不一樣操做，服務器向用戶返回的結果應該符合如下規範(具體是否須要返回須看前端需求)。
　　　　GET/collection：返回資源對象的列表（數組）
　　　　GET/collection/resource：返回單個資源對象
　　　　POST/collection：返回新生成的資源對象
　　　　PUT/collection/resource：返回完整的資源對象
　　　　PATCH/collection/resource：返回完整的資源對象
　　　　DELETE/collection/resource：返回一個空

　　十、最好作到Hypermedia，即返回結果中提供連接，連向其餘API(url)，使得用戶不查文檔，也知道下一步應該作什麼
　　　　{"link": {
　　　　　　"rel": "collection https://www.example.com/zoos",
　　　　　　"href": "https://api.example.com/zoos",
　　　　　　"title": "List of zoos",
　　　　　　"type": "application/vnd.yourformat+json"
　　　　}}