什麼是REST架構
詳細的解釋在網上大家都能搜到，我就不多說了
通俗的來說，REST是一種組織軟件的風格，而不是規範，它不強制你必須使用什麼樣的格式，只是建議你使用什麼樣的格式
它提出了一系列的想法，按照這些想法來組織軟件，按照這些想法來請求資源
REST提出的想法都可以通過現有技術的合理運用，沒有提出新的技術
它提供了關於API格式的想法，也就是我們所說的RESTfulAPI
這些想法、這種風格，叫做REST，下面就是它具體提出了哪些想法
大家可以在看完全部之後再回過頭來看這一段，就會有更深刻的理解
版本號
REST提出了關於版本的想法
假設我們的軟件新版本修改了一個函數，需要最新的客戶端支持，舊版本的無法運行
但是我們都知道，新版本發佈時大部分人不會更新，就會導致這樣的問題：
新舊版本客戶端都調用這個函數，但是這個函數被改過，而且新舊客戶端使用的都是同一個API請求資源，所以舊版本的客戶端不能用了
REST建議我們將函數最近的各個版本都留下來，給函數的每個版本賦予版本號，請求時帶上版本號就可以了
此時API就變成了這樣：
【GET】 /v1/users/{user_id} // 版本 v1 的查詢用戶列表的 API 接口
【GET】 /v2/users/{user_id} // 版本 v2 的查詢用戶列表的 API 接口
這樣新舊版本就都可以使用，我們需要同時維護函數的幾個版本，不必太多，只維護最近的幾個函數版本即可，廢棄很少有人用的版本，並強制使用那些版本的用戶升級
資源路徑
RESTful API對於資源路徑提出以下觀點：
- RESTful API 是以“資源”爲核心的，每一個URL代表的都是“資源”，所以URL應該只有名詞，可以有形容詞，但是儘量少用
- 無論資源是一個還是多個，名詞都使用複數
- 使用小寫字母
- 數字及下劃線來區分多個單詞
例如：【GET】 /v1/students/{student_id}【POST】 /v1/schools/{school_id}/students/{student_id} // 添加學校的學生，這個大家看到可能會有些莫名的疑惑，後面我們會說明POST這一方式 - 資源變化難以使用純名詞或形容詞來命名時，可以考慮使用一些特殊的 actions 命名
例如密碼修改：/{resources}/{resource_id}/actions/{action}【PUT】 /v1/users/{user_id}/password/actions/modify // 密碼修改
請求方式
REST認爲，對於不同種類的操作，請求時要使用不同的請求方式
| 請求方式 | 使用 |
|---|---|
| GET | 用於查詢資源 |
| POST | 用於創建新的資源 |
| PUT | 用於更新服務端的資源的全部信息 |
| PATCH | 用於更新服務端的資源的部分信息 |
| DELETE | 用於刪除服務端的資源。 |
比如
【GET】 /students/{student_id} 獲取學生信息
【GET】 /students 獲取所有學生列表
【POST】 /students 添加新學生
【PUT】 /students/{student_id} 修改該同學的所有信息
【PATCH】 /students/{student_id} 修改該同學的部分信息
【DELETE】 /students/{student_id} 刪除該同學
我們很少能看到除了【GET】和【POST】的其他請求方式，是因爲並不是所有瀏覽器都支持這些請求方式，但是所有瀏覽器都支持【GET】【POST】
查詢參數
- 分頁查詢
- offset 指定返回記錄的開始位置
- limit 指定返回記錄的數量
【GET】 /{version}/{resources}/{resource_id}?offset={field}&limit={filed} - 排序方式
orderby- asc升序，desc降序，自己規定其他排序方式
【GET】 /{version}/{resources}/{resource_id}[?orderby={filed} - 返回查詢總數
count【GET】 /{version}/{resources}/{resource_id}?count=[true|false] - 其他個性化查詢參數
【GET】 /v1/categorys/{category_id}/apps/{app_id}?enable=[1|0]&os_type={field}&device_ids={field,field,…}
不要過度設計，只返回需要的數據，但同時還要儘量保證API的彈性，以方便未來軟件擴展
爲了提高效率，可以考慮適當在數據庫添加索引
狀態碼
| 狀態碼 | 描述 |
|---|---|
| 200 | 請求成功 |
| 201 | 創建成功 |
| 400 | 錯誤的請求 |
| 401 | 未驗證 |
| 403 | 被拒絕 |
| 404 | 無法找到資源 |
| 409 | 資源衝突 |
| 500 | 服務器內部錯誤 |
異常響應
請求返回不是2xx的 HTTP 錯誤碼響應時，說明請求出現異常，返回時要攜帶錯誤信息
RESTful API 返回的數據一般時json格式
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"code": "INVALID_ARGUMENT",
"message": "{error message}",
"cause": "{cause message}",
"request_id": "01234567-89ab-cdef-0123-456789abcdef",
"host_id": "{server identity}",
"server_time": "2014-01-01T12:00:00Z"
}
這一點其實沒必要，因爲返回信息時會暴露很多信息，這些信息很可能會被人截獲，用這些知道的信息對你的軟件做些手腳
請求參數
- 對請求參數進行限制說明
- 例如批量查詢，要限制最多可以一次查詢多少人
【GET】 /v1/users/batch?user_ids=1001,1002 // 批量查詢用戶信息 參數說明 - user_ids: 用戶ID串，最多允許 20 個。 - 說明參數的格式
- 必填、選填、取值、長度等
【POST】 /v1/students // 創建新學生 請求內容 { "id": "1805010413", // 必填, 學號, max 10 "realname": "Tonited", // 必填, 學生姓名, max 10 "password": "123456", // 必填, 學生密碼, max 32 "email": "[email protected]", // 選填, 電子郵箱, max 32 "sex": 1 // 必填, 學生性別[1-男 2-女 3-其他 0-未知] }
響應參數
- 響應要符合請求方式的規範
| 請求方式 | 路徑 | 解釋 |
|---|---|---|
| 【GET】 | /{version}/{resources}/{resource_id} | 返回單個資源對象 |
| 【GET】 | /{version}/{resources} | 返回資源對象的列表 |
| 【POST】 | /{version}/{resources} | 返回新生成的資源對象 |
| 【PUT】 | /{version}/{resources}/{resource_id} | 返回完整的資源對象 |
| 【PATCH】 | /{version}/{resources}/{resource_id} | 返回完整的資源對象 |
| 【DELETE】 | /{version}/{resources}/{resource_id} | 狀態碼 200，返回完整的資源對象。 狀態碼 204，返回一個空文檔。 |
- 各種對象的返回方式
- 一條數據：返回對象的信息
HTTP/1.1 200 OK { "id" : "1805010413", "name" : "Tonited", "created_time": 2018091513550084, "updated_time": 2020041509120562, }- 一組數據：返回一組數據的封裝
HTTP/1.1 200 OK { "count":100, "items":[ { "id" : "1805010413", "name" : "Tonited", "created_time": 2018091513550084, "updated_time": 2020041509120562, }, ... ] }
完整案例
使用“獲取學生列表”的案例
【GET】 /v1/students?[&keyword=xxx][&enable=1][&offset=0][&limit=20] 獲取學生列表
功能說明：獲取學生列表
請求方式：GET
參數說明
- keyword: 模糊查找的關鍵字。[選填]
- enable: 啓用狀態[1-啓用 2-禁用]。[選填]
- offset: 獲取位置偏移，從 0 開始。[選填]
- limit: 每次獲取返回的條數，缺省爲 20 條，最大不超過 100。 [選填]
響應內容
HTTP/1.1 200 OK
{
"count":100,
"items":[
{
"id" : "1805010413",
"name" : "Tonited",
"created_time": 2018091513550084,
"updated_time": 2020041509120562
},
...
]
}
失敗響應
HTTP/1.1 403 UC/AUTH_DENIED
Content-Type: application/json
{
"code": "INVALID_ARGUMENT",
"message": "{error message}",
"cause": "{cause message}",
"request_id": "01234567-89ab-cdef-0123-456789abcdef",
"host_id": "{server identity}",
"server_time": "2014-01-01T12:00:00Z"
}
錯誤代碼
- 403 UC/AUTH_DENIED 授權受限
本文API示例來源及參考：《你怎麼理解 RESTful》李爲民