Rest Framework設計規範

• 2020 年 10 月 23 日
• 筆記
• django

Rest Framework

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

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

前後端分離

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

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

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

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

API設計

　　 對於後端的API介面設計，應該遵循RESTful AIP規範。

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

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

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

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

  //api.example.com/v1/
  //api.example.com/v2/
  

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

  //api.example.com/v1/book # 代表全部的書籍
  //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 //www.example.com/zoos",
    "href":  "//api.example.com/zoos",
    "title": "List of zoos",
    "type":  "application/vnd.yourformat+json"
  }}