RESTful概述
RESTful是目前最流行的一種互聯網軟件架構。它結構清晰、符合標准、易於理解、擴展方便，所以正得到越來越多網站的采用。
REST是Representational State Transfer的縮寫，是Roy Thomas Fielding在他2000年的博士論文中提出的。其提出的設計概念和准則為：
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接口訪問，不會使服務端資源的狀態發生改變。
規范建議
1. API盡量采用通過安全通道的HTTPS協議（https）。
2. 請求體與響應體統一通過json格式來承載，json使用Camel的命名規則，媒體類型需設置為“application/json”。
示例：
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 | 網關超時 |