1. 前言
REST 全稱為 :Resource Representational State Transfer. 是一種分布式超媒體系統( distributed hypermedia systems )架構風格。由Roy Fielding 提出。
REST API 也稱RESTful API, 其遵循REST架構規范的應用編程接口, 支持與RESTful WEB服務進行交互。簡單來講就是:符合REST架構風格的 WEB API 或WEB 服務就是 REST API。
2. REST 的6大指導原則
REST 定義了6個原則,這些原則使得一個WEB API 成為真正的RESTful API。
- 統一接口(Uniform interface)
開發者一旦熟悉了你的其中一個API,那么他就可以遵循類似的結構去使用其他API. - 客戶端服務器(Client-server)
只要不改變他們之間的接口,服務端和客戶端可以相互替換或獨立開發。 - 無狀態(Stateless)
客戶端上下文狀態不應該存儲在服務端,而應該有客戶端去管理程序的狀態 - 可緩存(Cacheable)
優秀的緩存可以部分或者完全消除客戶端和服務端的交互,最終提高應用的伸縮性和性能。 - 分層系統(Layered System)
REST可以允許你使用分層架構,讓你在服務器A上部署API, 服務器B上存儲數據,服務器C上進行權限驗證,客戶端不知道它實際連接的是哪個服務器。 - 按需編碼(Code on demand (optional))
這些規則可以幫組你構建真正的RESTful API ,所以盡量遵循著些規則。如果因為某些原因違反這些規則,事實上你還是在構建RESTful API ,只是不算真正的RESTful。
3. 最佳實踐
3.1 API名稱
API的名稱應該出現在URL中,API的標題也應該和名稱一致,所以起名子也是比較重要的一點,這決定了你的API是否容易讓人讀懂!
3.2 API的版本
API的版本應該遵循, MAJOR.MINOR.PATCH的結構,即主要.次要.補丁 。
如果有重大的改動,導致前后的版本不兼容應該升級主要版本, 比如從1.0 升級到2.0。
如果只是增加了一些特性,前后的版本都是兼容話,可以升級次要版本, 比如從1.0 升級到1.1.
如果有一些小的bug修改的話,可以在補丁版本的上升級,比如從 1.0 升級到1.0.1
例如:
https://mysite.com/v1/...
https://mysite.com/v2/...
3.3提供準確的API文檔
開發完成一個API之后,你需要讓API的使用者可以正確的使用它,那么就需要一份漂亮的API文檔了。
API文檔需要提供準確的請求路徑, 請求示例, 以及各種error時的狀態碼等。 可以使用Swagger等工具。
3.4資源路徑命名
- 資源名稱使用名詞,而不要使用動詞。
比如 POST : /cars 表示創建cars , GET: /cars 表示查詢cars 而不應該寫成/createCars , /getCars 等等。 - 獲取集合資源與獲取特定資源,統一使用復數來表示資源。
#獲取資源集合時使用復數名詞 例如 /schools #獲取特定資源 例如 /schools/{school-id} /schools/5 #獲取特定資源的子資源 例如 /schools/{school-id}/grades /schools/5/grades
3.5資源操作
RESTful API 使用HTTP 方法來對資源進行操作,相對應的一些常用操作如下:
HTTP method | 資源操作類型 |
---|---|
GET | 查詢集合,查詢單個資源 |
POST | Create 創建某個資源 |
PUT | update 更新資源 |
PATCH | 局部更新資源 |
DELETE | 刪除資源 |
創建資源 POST
使用POST方法 創建資源,此處可以創建單個資源或者資源集合。創建成功應該立馬返回HTTP 201, 二接受到resource并未立即添加資源則返回 HTTP 202 。例如: 使用POST: /schools 添加多個school資源, /schools/{school-id}/grades 添加某個school資源的grade,
查詢集合資源 及單個資源
例如: 使用 GET: /schools?type=PRIMARY 查詢所有的小學 使用 GET :/schools/{school-id}/grades 查詢某個學校的所有年級 GET :/schools/{school-id}/grades/{grade-id} 查詢某個學校某個年級
更新及修改資源 PUT/PATCH
更新個修改資源包含多種情況:
一種是完全更新,使用新的資源完全替換舊的資源。例如:PUT: /schools/{school-id}/address 更新某個客戶學校的地址信息
一種是修改局部更新,根據需求去更新修改原有的資源。
例如:PATCH: /schools/{school-id}/teachers 調整某個學校的老師
舉個例子
原有的資源如下:
{ "a":"A", "b":{ "c":"C", "d":"D" } }
當PATAH請求 如下:
PATCH HTTP/1.1 Content-Type: application/merge-patch+json { "a":"Z", "b":{ "d":null } }
修改后的resource如下
{ "a":"Z", "b":{ "c":"C" } }
刪除資源
刪除資源使用DELETE方法,刪除的方法有直接刪除,或者使資源不可見。
3.6請求參數
- 其余不是資源的參數應該出現在請求參數中。而且查詢參數應該出現在GET請求中,不應該出現在PUT,POST請求中。
- 請求參數應該使用駝峰命名法。
例如:GET /orders?startDate=2022-01-03&endDate=2022-02-03 DELETE /orders?status=EXPIRED
- 使用唯一查詢參數進行過濾
GET /orders?orderType=PAID GET /orders?amount >100.00
- 分頁查詢
API 使用offset={resultOffset}&limit={resultsPerPage} 進行分頁查詢, 并且以第0條數據為起始。 另外也可以使用 page={pageNumber}&limit={resultPerPage} 此時起始頁為第1頁 使用index={pageIndex}&limit={resultPerPage}, 每一頁可以返回上一頁或者下一頁的link 可以看如下例子: GET /orders?page=1&limit=15 第一頁的15條數據 GET /orders?offset=0&limit=15 第一頁的15條數據 GET /orders?page=5&limit=10 第五頁的10條數據 第51-60條 GET /orders?offset=50&limit=10 第51到60條數據 GET /orders?index=xxxxxxx&limit=10 同樣也可以表示第51-60條數據, 只不過對客戶端來說可能不知道第幾頁,response中應該包含有上一頁和下一頁的index
- 排序
API的排序功能是API非常重要的一個功能,可以使用sort,sort-by 即使沒有指出要排序,那么而應該給一個默認的排序。例如: GET /orders?sort=asc(date) /orders?sort=desc(date) GET /orders?sort=+date /orders?sort=-date GET /orders?sort=date.asc /orders?sort=date.desc GET /orders?sort=date&order-by=asc /orders?sort=-date&order-by=desc 多字段排序示例: GET /orders?sort=desc(date),asc(amount) GET /orders?sort=-date,+amount
3.7使用HTTP狀態碼處理錯誤
Http狀態碼有很多,這里列舉一些常見的。
http status | 描述 |
---|---|
2XX | SUCCESS |
200 | OK |
201 | Create |
202 | Accepted |
204 | No Content |
4XX | Client Error |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Request |
5xx | Server Errors |
500 | Internal Server Error |
總結
本篇介紹了一些REST API的一些食用方式,我們工作中可以根據一些各自的條件,作為參考。歡迎留言講講自己的一些實踐經驗!
-
存儲
+關注
關注
13文章
4468瀏覽量
86890 -
服務器
+關注
關注
12文章
9596瀏覽量
86957 -
API
+關注
關注
2文章
1554瀏覽量
63273 -
編程接口
+關注
關注
1文章
38瀏覽量
8094 -
REST
+關注
關注
0文章
33瀏覽量
9560
發布評論請先 登錄
相關推薦
FPGA設計的指導原則
設計復用的RTL指導原則
Jeep大指揮官試駕,性能全面解析
FPGA的指導性原則詳細資料說明

REST端口支持構建動態REST請求來使用RESTful API網絡
REST API是什么,如何使用REST端口

評論