Rest Framework設計規范

Rest Framework

　　 Rest Framework是前后端分離中用到的一種規范，它與框架本身無關，是一種軟件架構風格，全稱為Representational State Transfer。

　　 Rest Framework最顯著的特點就是將一切數據看作資源，同時對不同的請求方式做出不同的責任划分。這種結構理念也被稱為面向資源架構。

前后端分離

　　 不同於前后端混合開發中的接口，API接口主要用於為頁面提供數據。隨着前后端分離概念的出現，如今這種設計模式已是大勢所趨，前后端進行分離開發互不影響，而前端請求為頁面進行填充數據的接口則統稱為API接口。

　　 以下是前后端分離與混合開發的差異：

　　 前后端不分離：展示的頁面由后端決定，頁面上的數據由模板渲染而來。

　

　　 前后端分離：后端只返回頁面需要的數據，不再承擔模板的渲染工作，前后端開發耦合度較低。

API設計

　　 對於后端的API接口設計，應該遵循RESTful AIP規范。

• 　　 通信協議上應該采用HTTPS協議，確保數據安全

• 　　 API的域名應該具有一定的辨識度，如下url示例：

  https://api.example.com  # 以api開頭
  https://example.org/api/  # 以api結束
  

• 　　 API中應當放入版本號，如下示例：

  https://api.example.com/v1/
  https://api.example.com/v2/
  

• 　　 API請求路徑中只能含有名詞，不應該含有動詞。而且所用的名詞往往與數據庫的表格名對應，支持復數（極其重要），如下示例：

  https://api.example.com/v1/book # 代表全部的書籍
  https://api.example.com/v1/get_all_book # 不應該使用動詞，這是錯誤的形式
  

• 　　 由於API不含有動詞，所以我們可以根據不同的請求方式對處理邏輯進行划分，如下所示：

  GET（SELECT）：從服務器取出資源（一項或多項）。
  POST（CREATE）：在服務器新建一個資源。
  PUT（UPDATE）：在服務器更新資源（客戶端提供改變后的完整資源）。
  PATCH（UPDATE）：在服務器更新資源（客戶端提供改變的屬性）。
  DELETE（DELETE）：從服務器刪除資源。
  

  　　 下面是一些例子：

  GET /book：列出所有書籍
  POST /book：新建一本書籍
  GET /book/ID：獲取某個指定書籍的信息
  PUT /book/ID：更新某個指定書籍的信息（提供該書籍的全部信息）
  PATCH /book/ID：更新某個指定書籍的信息（提供該書籍的部分信息）
  DELETE /book/ID：刪除某本數據
  GET /book/ID/details：列出某本書籍的詳細信息
  DELETE /zoos/ID/author/ID：刪除某本指定書籍中的指定作者
  

• 　　 如果記錄數量很多，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。

  　　 下面是一些常見的參數。

  ?limit=10：指定返回記錄的數量
  ?offset=10：指定返回記錄的開始位置。
  ?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
  ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
  ?animal_type_id=1：指定篩選條件
  

• 　　 服務器向用戶返回的狀態碼和提示信息，常見的有以下一些（方括號中是該狀態碼對應的HTTP動詞）。

  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 - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。
  

• 　　 對於API的返回內容來說，如果狀態碼是4xx，則應該在返回信息中添加error及詳細的錯誤描述。

  {
      error: "Invalid API key"
  }
  

• 　　 對於API的返回結果來說，應該針對不同的請求操作，服務器向用戶返回的結果需符合以下規范。

  GET /collection：返回資源對象的列表（數組）
  GET /collection/resource：返回單個資源對象
  POST /collection：返回新生成的資源對象
  PUT /collection/resource：返回完整的資源對象
  PATCH /collection/resource：返回完整的資源對象
  DELETE /collection/resource：返回一個空文檔
  

• 　　 可以在返回的信息中添加鏈接，讓用戶知道及時不查看文檔，下一步也可以做什么。

  {"link": {
    "rel":   "collection https://www.example.com/zoos",
    "href":  "https://api.example.com/zoos",
    "title": "List of zoos",
    "type":  "application/vnd.yourformat+json"
  }}