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"
  }}