RESTful規範

什麼是RESTful

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

1、URI規範

1.不用大寫；

2.用中槓 - 不用下槓 _ ；

3.參數列表要encode；

4.URI中的名詞表示資源集合，使用複數形式。

5.在RESTful架構中，每一個網址表明一種資源（resource），因此網址中不能有動詞，只能有名詞（特殊狀況可使用動詞），並且所用的名詞每每與數據庫的表格名對應。

資源集合 vs單個資源

URI表示資源的兩種方式：資源集合、單個資源。

資源集合：

       /zoos //全部動物園

       /zoos/1/animals //id爲1的動物園中的全部動物

單個資源：

       /zoos/1//id爲1的動物園

       /zoos/1;2;3//id爲1，2，3的動物園

避免層級過深的URI

在url中表達層級，用於 按實體關聯關係進行對象導航 ，通常根據id導航。

過深的導航容易致使url膨脹，不易維護，如 GET /zoos/1/areas/3/animals/4 ，儘可能使用查詢參數代替路徑中的實體導航，如 GET/animals?zoo=1&area=3 ；

2、   版本

應該將API的版本號放入到URI中

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

3、 Request

HTTP方法

經過標準HTTP方法對資源CRUD：

GET：查詢（從服務器取出資源一項或多項）

GET /zoos

GET /zoos/1

GET/zoos/1/employees

 

POST：建立單個新資源。 POST通常向「資源集合」型uri發起

POST/animals  //新增動物

POST/zoos/1/employees //爲id爲1的動物園僱傭員工

PUT：更新單個資源（全量），客戶端提供完整的更新後的資源。與之對應的是 PATCH，PATCH負責部分更新，客戶端提供要更新的那些字段。 PUT/PATCH通常向「單個資源」型uri發起

PUT/animals/1

PUT /zoos/1

 

DELETE：刪除

DELETE/zoos/1/employees/2

DELETE/zoos/1/employees/2;4;5

DELETE/zoos/1/animals  //刪除id爲1的動物園內的全部動物

 

HEAD / OPTION/ PATCH用的很少，就很少解釋了。

HEAD：獲取資源的元數據

OPTIONS：獲取信息，關於資源的哪些屬性是客戶端能夠改變的

PATCH：在服務器更新資源（客戶端提供改變的屬性）

 

安全性和冪等性

1.     安全性 ：不會改變資源狀態，能夠理解爲只讀的；

2.     冪等性 ：執行1次和執行N次，對資源狀態改變的效果是等價的。

.	安全性	冪等性
GET	√	√
POST	×	×
PUT	×	√
DELETE	×	√

安全性和冪等性均不保證反覆請求能拿到相同的response。以 DELETE爲例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是容許的。

複雜查詢

查詢能夠捎帶如下參數：

.	示例	備註
過濾條件	?type=1&age=16	容許必定的uri冗餘，如 /zoos/1 與 /zoos?id=1
排序	?sort=age&order=asc	指定返回結果按照哪一個屬性排序，以及排序順序
投影	?whitelist=id,name,email
分頁	? page=2&per_page=100	指定第幾頁，以及每頁的記錄數

Bookmarker

常用的、複雜的查詢標籤化，下降維護成本。

如：GET /trades?status=closed&sort=created,desc

快捷方式：GET /trades#recently-closed或者GET /trades/recently-closed

 

狀態碼

    服務器向用戶返回的狀態碼和提示信息，常見的有如下一些（方括號中是該狀態碼對應的HTTP動詞）。

§200 OK - [GET]：服務器成功返回用戶請求的數據，該操做是冪等的（Idempotent）。

§201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。

§202 Accepted - [*]：表示一個請求已經進入後臺排隊（異步任務）

§204 NO CONTENT - [DELETE]：用戶刪除數據成功。

§400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操做，該操做是冪等的。

§401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。

§403 Forbidden - [*] 表示用戶獲得受權（與401錯誤相對），可是訪問是被禁止的。

§404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操做，該操做是冪等的。

§406 Not Acceptable - [GET]：用戶請求的格式不可得（好比用戶請求JSON格式，可是隻有XML格式）。

§410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再獲得的。

§422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個對象時，發生一個驗證錯誤。

§500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將沒法判斷髮出的請求是否成功。

狀態碼的徹底列表參見這裏

 

URI失效

隨着系統發展，總有一些API失效或者遷移，對失效的API，返回404 not found 或 410 gone；對遷移的API，返回 301重定向。

 

4、Response

1.    不要包裝：

response的 body 直接就是數據，不要作多餘的包裝。錯誤示例：

{

   "success":true,

   "data":{"id":1,"name":"xiaotuan"},

}

2.    各HTTP方法成功處理後的數據格式：

·	response 格式
GET	單個對象、集合
POST	新增成功的對象
PUT/PATCH	更新成功的對象
DELETE	空

 

5、錯誤處理

1.     不要發生了錯誤但給2xx響應，客戶端可能會緩存成功的http請求；

2.     正確設置http狀態碼，不要自定義；

3.     Response body提供

即:返回的信息中將error做爲鍵名，出錯信息做爲鍵值便可

1)錯誤的代碼（日誌/問題追查）；

2)錯誤的描述文本（展現給用戶）。

 

對第三點的實現稍微多說一點：

Java服務器端通常用異常表示 RESTful API的錯誤。API 可能拋出兩類異常：業務異常和非業務異常。 業務異常 由本身的業務代碼拋出，表示一個用例的前置條件不知足、業務規則衝突等，好比參數校驗不經過、權限校驗失敗。 非業務類異常 表示不在預期內的問題，一般由類庫、框架拋出，或因爲本身的代碼邏輯錯誤致使，好比數據庫鏈接失敗、空指針異常、除0錯誤等等。

業務類異常必須提供2種信息：

1.     若是拋出該類異常，HTTP響應狀態碼應該設成什麼；

2.     異常的文本描述；

在Controller層使用統一的異常攔截器：

1.     設置 HTTP響應狀態碼：對業務類異常，用它指定的 HTTPcode；對非業務類異常，統一500；

2.     Response Body的錯誤碼：異常類名

3.     Response Body的錯誤描述：對業務類異常，用它指定的錯誤文本；對非業務類異常，線上能夠統一文案如「服務器端錯誤，請稍後再試」，開發或測試環境中用異常的 stacktrace，服務器端提供該行爲的開關。

經常使用的http狀態碼及使用場景：

狀態碼	使用場景
400 bad request	經常使用在參數校驗
401 unauthorized	未經驗證的用戶，常見於未登陸。若是通過驗證後依然沒權限，應該 403（即 authentication和 authorization的區別）。
403 forbidden	無權限
404 not found	資源不存在
500 internal server error	非業務類異常
503 service unavaliable	由容器拋出，本身的代碼不要拋這個異常

 

6、其餘

（1）API的身份認證應該使用OAuth2.0框架

（2）服務器返回的數據格式，應該儘可能使用JSON，避免使用XML

（3）比較複雜的接口不能肯定是使用POST仍是PUT時，要看具體的業務層代碼，看看接口產生的結果是否冪等，若是冪等用PUT，相反用POST

      如：接口接收到一資源，資源存在更新，不存在插入新數據，這個接口就要用PUT

 

參考：https://blog.csdn.net/u013731455/article/details/56278168

 

restful 規範

		1. 根據method不一樣，進行不一樣操做
			GET/POST/PUT/DELETE/PATCH
		2. 面向資源編程
			http://www.nnblog.com/blog
		
		3. 體現版本
			http://www.nnblog.com/v1/blog
			http://www.nnblog.com/v2/blog
			
			https://v4.bootcss.com/
			https://v3.bootcss.com/
		4. 體現是API
			http://www.nnblog.com/api/v1/blog
			http://www.nnblog.com/api/v2/blog	
			
			http://api.nnblog.com/v1/salary	
			http://api.luffycity.com/v2/blog	
		5. https
			https://www.nnblog.com/api/v1/blog
			https://www.nnblog.com/api/v2/blog	
			
		6. 響應式設置狀態碼
			200
			300
			400
			500
			return HttpResponse('adfasdf',status=300)
		
		7. 條件 
			https://www.nnblog.com/api/v2/blog?page=1&size=10
		
		8. 返回值
			https://www.nnblog.com/api/v2/salary
			GET: 全部列表
			{
				code: 10000,
				data: [    
					{'id':1,'title':'a'},
					{'id':1,'title':'b'},
					{'id':1,'title':'c'},
				]
			}
				
			POST: 返回新增的數據
				{'id':1,'title':'高亮'}
				
			https://www.nnblog.com/api/v2/salary/1/
			GET: 獲取單條數據
					{'id':1,'title':'d'}
			PUT：更新
					{'id':1,'title':'e'}
			PATCH: 局部更新
					{'id':1,'title':'f'}
			DELETE：刪除
				
		9. 返回錯誤信息
			{
				code: 100001,
				error: 'xxx錯誤'
			}
		
		10. Hypermedia API
			ret = {
				code: 1000,
				data:{
					id:1,
					name:'付勇',
					depart_id:http://www.nnblog.com/api/v1/blog/8/
				}
			}