RESTful規範建議

RESTful概述

RESTful是目前最流行的一種互聯網軟件架構。它結構清晰、符合標準、易於理解、擴展方便,因此正獲得愈來愈多網站的採用。json

REST是Representational State Transfer的縮寫,是Roy Thomas Fielding在他2000年的博士論文中提出的。其提出的設計概念和準則爲:api

1. 網絡上的全部事物均可以抽象爲資源緩存

2. 每一個資源都應該有惟一的標識(identifier),對資源的操做不會改變標識安全

3. 全部的操做都是無狀態的服務器

4. 使用標準方法(GET、POST、PUT、PATCH、DELETE)操做資源網絡

 

RESTful使用

HTTP方法 URI 描述 冪等 安全
 GET  /api/members  獲取成員列表  是  是
 GET  /api/members/{id}   獲取指定成員  是  是
 POST  /api/members  建立一個成員  否  否
 PUT  /api/members/{id}   更新成員全部信息  是  否
 PATCH  /api/members/{id}   更新成員部分信息  是  否
 DELETE  /api/members/{id}   刪除指定成員  是  否
HTTP方法 URI 描述 冪等 安全
 GET  /api/groups  獲取羣組列表  是  是
 GET  /api/groups/{id}  獲取指定羣組  是  是
 POST  /api/groups  建立一個羣組  否  否
 PUT  /api/groups/{id}  更新羣組全部信息  是  否
 PATCH  /api/groups/{id}  更新羣組部分信息  是  否
 DELETE  /api/groups/{id}  刪除指定羣組  是  否
 GET  /api/groups/{id}/members  獲取指定羣組下的成員  是  是
 GET  /api/groups/{id}/members/{memberId}  獲取指定羣組下的指定成員  是   是

冪等性:同一個RESTful接口的屢次訪問,獲得的資源狀態是相同的。架構

安全性:對該RESTful接口訪問,不會使服務端資源的狀態發生改變。app

 

規範建議

1. API儘可能採用經過安全通道的HTTPS協議(https)。dom

  

2. 請求體與響應體統一經過json格式來承載,json使用Camel的命名規則,媒體類型需設置爲「application/json」。ide

示例:

Request

  Accept: application/json

  Content-Type: application/json

 

Response

  Content-Type: application/json

 

3. 請求體與響應體統一採用UTF-8編碼格式,時間統一使用UTC格式:yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'。

 

4. URI模版:/{domain}/{service or module}/api/{version}/{resource},URI應全爲小寫字母,短語單詞使用「-」分隔。

名稱 說明 示例
 domain  領域名稱,不須要區分領域時,能夠不指定

 education(教育領域)

 finance(金融領域)

 game(遊戲領域)

 service or module  服務或模塊名

 account(帳戶模塊)

 order(訂單服務)

 storage(庫存服務)

 version  版本號

 v1

 v2

 v3

 resource  服務或模塊內資源

 users(用戶)

 products(產品)

 members(成員)

 

5. 資源增、刪、改、查外的操做,採用模板:/{domain}/{service or module}/api/{version}/{resource}/action/{action}。

示例:/common/account/api/v1/users/action/login

 

響應消息建議

1. 獲取資源列表成功返回200,響應消息體中包含記錄總條數、當前頁碼、每頁記錄,以及對應的資源。

示例:

Response Body

{

  "total": xxx,

  "pageIndex": xxx,

  "pageSize":xxx,

  "records":[

    { "id": xxx, "name":"xxx" },

    { "id": xxx, "name":"xxx" }

  ]

}

 

2. 獲取指定資源成功返回200,響應消息體中包含該資源的信息。

 

3. 建立資源成功返回201,並在響應消息頭中包含定位該資源的地址。

示例:

Response Headers

{
  "pragma": "no-cache",
  "server": "xxx",
  "content-type": "application/json; charset=utf-8",
  "location": "https://xxx/api/users/xxx", //資源訪問地址
  "content-length": "xxx"
}

 

4. 資源更新成功返回200,並在響應消息中體返回更新後的資源內容。

 

5. 資源刪除成功返回204,響應消息體無內容。

 

6. 針對400 Bad Request客戶端錯誤,能夠在響應消息體中擴展狀態碼。

示例:

Response Code

400 Bad Request

Response Body

{

  "code": 400001,

  "message": "用戶名或密碼錯誤"

}

 

----------------------------------------------------------

Response Code

400 Bad Request

Response Body

{

  "code": 400002,

  "message": "郵箱已存在"

}

 

----------------------------------------------------------

Response Code

400 Bad Request

Response Body

{

  "code": 400003,

  "message": "郵箱地址錯誤"

}

 

7. 針對5XX的服務端錯誤,只在響應消息體中提供簡單提示,不可打印錯誤日誌信息。

示例:

Response Body

{

  "message": "內部錯誤,請稍後再試或聯繫管理員"

}

 

7. 其餘客戶端錯誤的響應碼,只在響應消息體中提供相應提示。

示例:

Response Code

401 Unauthorized

Response Body

{

  "message": "用戶未登陸"

}

 

----------------------------------------------------------

Response Code

403 Forbidden

Response Body

{

  "message": "權限不足"

}

 

----------------------------------------------------------

Response Code

404 Not Found

Response Body

{

  "message": "請求資源不存在或已被刪除"

}

 

常見響應碼

響應碼 說明
 200 OK  請求已成功
 201 Created  資源已建立
 204 No Content  請求已成功,但無返回內容
 304 Not Modified  緩存有效
 400 Bad Request  語義有誤,當前請求沒法被服務器理解,請求參數錯誤
 401 Unauthorized  當前請求須要用戶認證(登陸)
 403 Forbidden  用戶已認證(登陸),但權限不足
 404 Not Found  請求源未在服務器上被發現
 405 Method Not Allowed  請求方法不能被用於請求相應的資源,如使用PUT方法訪問只接受POST方法的API
 500 Internal Server Error  服務端內部錯誤
 502 Bad Gateway  網關錯誤
 504 Gateway Timeout  網關超時
相關文章
相關標籤/搜索