RESTful是目前最流行的一種互聯網軟件架構。它結構清晰、符合標準、易於理解、擴展方便,因此正獲得愈來愈多網站的採用。json
REST是Representational State Transfer的縮寫,是Roy Thomas Fielding在他2000年的博士論文中提出的。其提出的設計概念和準則爲:api
1. 網絡上的全部事物均可以抽象爲資源緩存
2. 每一個資源都應該有惟一的標識(identifier),對資源的操做不會改變標識安全
3. 全部的操做都是無狀態的服務器
4. 使用標準方法(GET、POST、PUT、PATCH、DELETE)操做資源網絡
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 | 網關超時 |