【轉載】RESTful API 規範

RESTful是一種設計風格,而不是標準。它提供了一組設計原則和約束條件,主要用於客戶端和服務器交互類軟件的設計。基於這個風格設計的軟件可以更簡潔、更有層次、更易於實現緩存等機制。

1. 協議

RESTful API 總是使用 HTTPS協議進行通信。

2. 域名

應該儘量將 API 部署在專用域名下,例如:https://api.example.com

3. 版本

應該將 API 版本號放入 URL 中,例如:https://api.example.com/v1/。

也可以將版本號放在 HTTP Header 中,但不如放入 URL 中方便和直觀。

4. 實體

在 RESTful 架構中,每個地址代表一種資源,所以地址中不能有動詞,只能有名詞,且實體名稱均以複數形式表示。例如:

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

5. 動詞

業務邏輯總是能對應到數據庫的增刪改查上,其恰好與 GET、POST、PUT、DELETE 四種 HTTP Method 對應。因此,REST 使用 HTTP Method 標識操作類型,避免在 URL 中顯示指明操作類型。比如,使用 GET /users 代替 GET /users/qry。例如:

GET /zoos:列出所有動物園
POST /zoos:新建一個動物園
GET /zoos/id:獲取某個指定動物園的信息
PUT /zoos/id:更新某個指定動物園的信息
DELETE /zoos/id:刪除某個動物園
GET /zoos/id/animals:列出某個指定動物園的所有動物
DELETE /zoos/id/animals/id:刪除某個指定動物園的指定動物

6. 狀態碼

REST 使用狀態碼標識請求的執行結果,而不是正文中的部分字段。

200 OK - [GET]:服務器成功返回用戶請求的數據
201 CREATED - [POST/PUT/PATCH]:用戶新建或修改數據成功
202 Accepted - [*]:請求已經進入後臺排隊(異步任務)
204 NO CONTENT - [DELETE]:用戶刪除數據成功
400 INVALID REQUEST - [POST/PUT/PATCH]:用戶發出的請求有錯誤,服務器沒有進行新建或修改數據的操作
401 Unauthorized - [*]:表示用戶沒有權限(令牌、用戶名、密碼錯誤)
403 Forbidden - [*] 表示用戶得到授權,但是訪問是被禁止的
404 NOT FOUND - [*]:用戶發出的請求針對的是不存在的記錄,服務器沒有進行操作
406 Not Acceptable - [GET]:用戶請求的格式不可得
410 Gone -[GET]:用戶請求的資源被永久刪除,且不會再得到的
422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時,發生一個驗證錯誤
500 INTERNAL SERVER ERROR - [*]:服務器發生錯誤,用戶將無法判斷髮出的請求是否成功
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章