RestFramework——API設計規范

 

what's the RESTful

　　RestFramework是一個能快速為我們提供API接口，方便我們編程的框架。API是后端編程人員寫的，為了讓前端拿數據的一個接口，通常就是以url的形式存在。

　　每個項目總有第一個人做基礎構架，這個時候就不是僅僅實現一個API就OK了，需要考慮更多的事情，包括

• • 　　統一的異常處理

  • 　　API權限

  • 　　統一的參數校驗

  • 　　緩存如何可以做的更簡單統一

  • 　　認證

  • 　　統一的查詢過濾

  • 　　代碼分層

RestFramework能很好的幫我們做這些事情。

了解RestFramework之前我們首先要知道什么是REST：

• REST是一種標准，restful是一種規范，根據產品需求需要定出一份方便前后端的規范，與協議（如HTTP協議）不同，不是所有的標准要求都需要遵循。
• REST與技術無關，代表的是一種軟件架構風格，REST是Representational State Transfer的簡稱，中文翻譯為“表征狀態轉移”
• REST從資源的角度類審視整個網絡，它將分布在網絡中某個節點的資源通過URL進行標識，客戶端應用通過URL來獲取資源的表征，獲得這些表征致使這些應用轉變狀態
• 所有的數據，不過是通過網絡獲取的還是操作（增刪改查）的數據，都是資源，將一切數據視為資源是REST區別與其他架構風格的最本質屬性
• 對於REST這種面向資源的架構風格，有人提出一種全新的結構理念，即：面向資源架構（ROA：Resource Oriented Architecture）

 

API設計規范

　　首先我們要知道，API並不是必須的，如果整個項目只有你一個人或者很少的人完成，完全可以直接用Django的模板引擎渲染發送到前端后直接操作。API的使用主要是為了解決多人開發，特別是前后端分離的情況。因為前端人員在制作頁面時必然會需要向后端要數據，但是假如前后端是分離的，就不能用Django的render了，大部分情況前端會用ajax發送請求，后端人員則發送JSON字符串給前端，前端再反序列化后進行使用。這個時候其實我們設計一套API出來，就能使我們的任務輕松很多。所以，RestFramework就應運而生了。

　　API與用戶的通信協議，本質上是HTTPs協議。

使用RestFramework設計API有一套規范，即RESTful，為了不平添與你合作開發的人的煩惱，我們還是要遵循這些規范。那么到底有哪些規范呢？

1. 域名：域名上要顯示你使用了API，我們有兩種方式
   • https://api.example.com                  方式一：將API部署在專用域名上（是官網的推薦方式，但這么做會存在跨域問題）
   • https://example.org/api/                  方式二： 寫在路徑上，API很簡單
2. 版本：我們的項目在開發過程中會進行功能的添加及優化，這個時候我們通常會為每一個版本設定一個版本號，版本號的顯示也有兩種方式
   • https://api.example.com/v1/　　     方式一： 寫在路徑上，API很簡單
   • https://v1.example.com                   方式二：將版本號部署在專用域名上（同樣會存在跨域問題， 跨域時會引發發送多次請求）
3. 路徑：視網絡上任何東西都是資源，所以路徑均使用名詞表示（可復數）
   • https://api.example.com/v1/zoos
   • https://api.example.com/v1/animals
4. 請求方式：
   • GET      ：從服務器取出資源（一項或多項）
   • POST    ：在服務器新建一個資源
   • PUT      ：在服務器更新資源（客戶端提供改變后的完整資源——全部修改）
   • PATCH  ：在服務器更新資源（客戶端提供改變的屬性——部分修改）
   • DELETE ：從服務器刪除資源
5. 過濾：通過在URL上傳參的方式，有GET請求獲取相應的數據
   • https://api.example.com/v1/zoos?limit=10：指定返回數據的數量
   • https://api.example.com/v1/zoos?offset=10：指定返回數據的開始位置
   • https://api.example.com/v1/zoos?page=2&per_page=100：指定第幾頁以及每頁的數據數量
   • https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序
   • https://api.example.com/v1/zoos?animal_type_id=1：指定篩選條件
6. 狀態碼：我們可以通過狀態碼來判斷請求的狀態，以處理相應的請求。在狀態碼是4開頭時，應該捕捉相應錯誤並返回錯誤信息

   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 - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。
   
   更多看這里：http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

   {error: "Invalid API key"}#錯誤信息因用error作為key

7. 返回結果：針對不同操作，服務器向用戶返回的結果應該符合以下規范。
   • GET/collection：返回資源對象的列表
   • GET/collection/resource：返回單個資源對象
   • POST/collection：返回新生成的資源對象
   • PUT/collection/resource：返回完整的資源對象
   • PATCH/collection/resource：返回完整的資源對象
   • DELETE/collection/resource：返回一個空文檔
   • 　
8. Hypermedia API：RESTful API最好做到Hypermedia，即返回結果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應該做什么。

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