Restful-API設計最佳實戰--Django播客系統(五)

Restful-API設計最佳實戰–Django播客系統(五)

RESTFul

• REST(Representational State Transfer),表現層狀態轉移。
• 它首次出現在2000年Roy Fielding的博士論文中，Roy Fielding是HTTP規範的主要編寫者之一。
• 表現層是資源的表現層，對於網絡中的資源就需要URI(Uniform Resource Identifier)來指向。

1.協議

• 使用HTTP或者HTTPS。對外若有安全性要求，可以使用HTTPS。但是內部服務間調用可以使用HTTP或HTTPS。

2.HTTP方法

• HTTP請求中的方法表示執行的動作

常用方法(動詞)	說明
GET	獲取資源
POST	創建新的資源
PUT	更新資源
PATCH	部分更新資源
DELETE	刪除資源

3.使用名稱

URL指向資源，在URL路徑的描述中，只需要出現名稱，而不要出現動詞。動詞由HTTP方法提供。
不要單複數混用，建議名稱使用複數。
Restful的核心是資源，URL應該指向資源，所以應該是使用名稱表達式，而不是動詞表達。

方法	路徑	說明
GET	/posts	返回所有文章
GET	/posts/10	返回id爲10的文章
POST	/posts	創建新的文章
PUT	/posts/10	更新id爲10的文章
DELETE	/posts/10	刪除id爲10的文章
PATCH	/posts/10	部分更新id爲10的文章數據

• 不要出現如下的訪問路徑

/getAllPosts
/addPost
/updatePost
/delPost

• GET方法只是獲取資源，而不是改變資源狀態。改變資源請使用POST,PUT,DELETE等方法。

• 例如：使用GET /posts/10就可以獲取資源了，但是卻使用Get /posts/10/del或GET /posts/10?v=del,本意是想刪除。但這樣不好，GET方法請求只爲獲取資源，不要改變資源狀態。

• 子資源的訪問

方法	路徑Endpoint	說明
GET	/posts/10/authors	返回id爲10的文章的所有作者
GET	/posts/10/authors/8	返回id爲10的文章的作者中id爲4的

4.集合功能

• 過濾Filtering
  1. 指定過濾條件GET /posts?tag=python
• 排序Sorting
  1. 指定排序條件。有很多種設計風格，例如使用+表示asc,-表示desc。GET /posts?sort=+title,-id獲取GET /posts?sort=title_asc,id_desc
• 分頁Pagination
  1. 一般情況下，查詢返回的記錄數非常多，必須分頁。GET /posts?page=58&size=20

5.狀態碼

• 使用HTTP響應的狀態碼錶示動作的成功與否。
• 2xx表示用戶請求服務端成功的處理；4xx表示用戶請求的錯誤；5xx表示服務器端出錯了。

Status Code	說明	Method	說明
200	OK	GET	成功獲取資源
201	CREATED	POST,PUT,PATCH	成功創建或修改
204	NO CONTENT	DELETE	成功刪除資源
400	Bad Request	ALL	請求中有錯誤，例如：GET時參數有問題，PUT時提交的數據錯誤等
401	Unauthorized	ALL	權限未通過認證
403	Forbidden	ALL	有無權限都禁止訪問該資源
404	Forbidden	ALL	請求資源不存在
500	internal Server Error	ALL	服務器端錯誤

• 詳細狀態碼參考https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

6.錯誤處理

• 在Restful API設計中，錯誤處理也非常重要。單單從無狀態碼中無法詳盡描述錯誤的信息。

1. 返回消息

   {error:"user NOT Found"}
   

2. 從錯誤消息中瞭解到錯誤號、錯誤信息、錯誤描述等信息。甚至更詳細的信息可以通過code查閱文檔

   {
       "code":10056,
       "message":"Invalid ID",
       "description":"More details"
   }
   

7.版本

• 強烈要求使用版本、版本號使用簡單數字，例如v2。
• 2種風格
  1. http://api.xdd.com/v1/posts/10 這種風格會跨域，適合較大的項目
  2. http://www.xdd.com/api/v1/posts/10

8. 返回結果

方法	路徑	說明
GET	/posts	返回所有文章的列表
GET	/posts/10	返回id爲10的文章對象
POST	/posts	創建更新的文章並返回這個對象
PUT	/posts/10	更新id爲10的文章並返回這個對象
DELETE	/posts/10	刪除id爲10的文章返回一個空對象
PATCH	/posts/10	部分更新id爲10的文章數據並返回這個對象

• 數據一律採用JSON格式