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

文章目錄

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

• ​​RESTFul​​

• ​​1.協定​​
• ​​2.HTTP方法​​
• ​​3.使用名稱​​
• ​​4.集合功能​​
• ​​5.狀态碼​​
• ​​6.錯誤處理​​
• ​​7.版本​​
• ​​8. 傳回結果​​

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

1. 從錯誤消息中了解到錯誤号、錯誤資訊、錯誤描述等資訊。甚至更詳細的資訊可以通過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

• 資料一律采用JSON格式