簡介
REST（Representational State Transfer）：表象層狀態轉變
RESTful對api進行規范和約束，使得api統一規范，增強api的可讀性，便於開發。
設計原則
1、每一個URI代表一種資源
2、客戶端通過四個HTTP動詞（get、post、put、delete），對服務器端資源進行操作
因此，這種風格的接口url中沒有動詞，而是通過四個HTTP動詞（get、post、put、delete）來代表動作。
Http動詞
分別對應四種基本操作：
- GET用來獲取資源
- POST用來新建資源（也可以用於更新資源）
- PUT用來更新資源
- DELETE用來刪除資源
具體實施
版本控制
如github開放平台的API：
http://
developer.github.com/v3
/ 可以發現，一般的項目加版本v1，v2，v3版本號，為的是兼容一些老版本的接口，這個加版本估計只有大公司大項目才會去使用。
參數命名規范
query parameter可以采用
駝峰命名法，也可以采用下划線命名的方式，推薦采用
下划線命名的方式，據說后者比前者的識別度要高，其中，做前端開發基本都后后者，而做服務器接口開發基本用前者。
http://example.com/api/users/today_login 獲取今天登陸的用戶 http://example.com/api/users/today_login&sort=login_desc 獲取今天登陸的用戶、登陸時間降序排列
url命名規范
API 命名應該采用約定俗成的方式，保持簡潔明了。在RESTful架構中，每個url代表一種資源，所以url中不能有動詞，只能有名詞，並且名詞中也應該使用復數。實現者應使用相應的Http動詞GET、POST、PUT、PATCH、DELETE、HEAD來操作這些資源即可
不規范的的url，冗余沒有意義，形式不固定，不同的開發者還需要了解文檔才能調用。
http://example.com/api/getallUsers //GET 獲取所有用戶 http://example.com/api/getuser/1 //GET 獲取標識為1用戶信息 http://example.com/api/user/delete/1 //GET/POST 刪除標識為1用戶信息 http://example.com/api/updateUser/1 //POST 更新標識為1用戶信息 http://example.com/api/User/add //POST添加新的用戶
規范后的RESTful風格的url，形式固定，可讀性強，根據users名詞和http動詞就可以操作這些資源。名詞可以使用駝峰命令或者"_"分割
http://example.com/api/users //GET 獲取所有用戶信息 http://example.com/api/users/1 //GET 獲取標識為1用戶信息 http://example.com/api/users/1 //DELETE 刪除標識為1用戶信息 http://example.com/api/users/1 //Patch 更新標識為1用戶部分信息,包含在div中 http://example.com/api/users //POST 添加新的用戶
統一返回數據格式
對於合法的請求應該返回統一的數據格式，對於返回數據，通常會包含如下字段。
- code——即一個整數類型的HTTP響應狀態碼。
- message——即返回給前端的信息，正常返回時是"success"，當值為 "fail" 或 "error" 時，用於顯示錯誤信息。
- data——即前端需要返回的數據。 當值為 "fail" 或 "error" 時，設置為null。
返回成功的響應json格式：
{
"code": 200,
"message": "success",
"data": {
"name": "小明",
"age": 16,
"sex": 0
}
}
返回失敗的響應json格式：
{
"code": 401,
"message": "error message",
"data": null
}
http狀態碼
2**：成功–表示請求已被成功接收。
200（成功）用瀏覽器打開一個網頁，正常情況下都會返回200HTTP狀態碼。
201（創建成功）代表資源創建成功
3**：重定向（URL跳轉），要完成請求必須進行更進一步的操作。
300（多種選擇）下載一部片，服務器有 avi、mp4 等格式。
301（永久移動）請求的網頁已永久移動到新位置，自動將請求者轉到新位置。
304 (頁面未修改) ：按F5刷新（第二次訪問）。
4**：客戶端錯誤，請求有語法錯誤或請求無法實現。
400（錯誤請求）服務器不理解請求的語法。
401（未授權）沒有攜帶認證信息或攜帶了錯誤的認證信息，而沒有通過認證。（未登錄時）
403（禁止）攜帶了正確的認證信息，服務器認為該用戶對該資源無權訪問。(https輸成了http)
404（未找到）請求的內容不存在。
5**：服務器端錯誤，服務器未能實現合法的請求。
500（服務器內部錯誤）服務器自己出現錯誤。
502（網關錯誤）服務器作為網關或代理，從上游服務器收到無效響應。
503（服務器不可用）服務器超載或停機維護不可用。
查詢參數
在請求數據時，客戶端經常會對數據進行過濾和分頁等要求，而這些參數推薦采用HTTP Query Parameter的方式實現。
//搜索用戶，最近登錄 http://example.com/api/users?recently_login_day=3 //搜索用戶，按照注冊時間降序 http://example.com/api/users?sort=register_time_desc //搜索用戶，按照注冊時間升序、活躍度降序 http://example.com/api/users?sort=register_time_asc,liveness_desc
復雜參數
xxx
后端案例
GET請求
## url路徑傳參1
http://localhost:8080/api/user?id=1
后端要獲取code參數，可以使用@RequestParam注解
## url路徑參數2
http://localhost:8080/api/user/1
后端使用@PathVariable可以接收路徑參數1。
POST請求
## Headers傳值
在這里我們把Content-Type設置為了json格式。
我們還可以在headers里面加入別的參數，比如token。
后端可以通過HttpServletRequest獲取請求頭的內容，如：
request.getHeader(string name)
request.getHeaders(String name)
request.getHeaderNames()
### Body傳值
一般來說，使用json格式傳值，如下圖：
后端接受這種數據應該采用@RequestBody
@PostMapping(value = "/user") public ApiResult addUser(@RequestBody UserDTO userDTO) { return userService.add(userDTO); }