RESTful 架構和 RESTful API 設計總結
作者:智明書
鏈接:https://www.jianshu.com/p/955eb2faa354
REST 這個詞是 2000 年 Roy Fielding 在他的博士論文中提出的,Fielding 參與了 http 協議的設計,也是 Apache web server 項目的參與者。他的這篇博士論文可以說對互聯網的軟件設計產生了深遠的影響。但是從字面上理解 REST(Representational State Transfer, 表現層狀態轉移) 是非常抽象的。因此,本篇文章試圖將 REST 進行拆解,分別從以下幾個部分來進行解讀:
Resource 資源
REST 忽略了主語,全稱應該是資源的表現層狀態轉移。所謂資源就是互聯網上的各種資源,比如文本、圖片、音頻、視頻等。在互聯網上通過 URI 指定唯一的資源,所謂的’**上網‘**就是通過調用資源的 URL 來跟互聯網上的一系列資源進行互動。
注:URI 只代表資源的實體,嚴格地說,有些網址最後的.html
後綴名是不必要的,因爲這個後綴名錶示格式,屬於 "表現層" 範疇,而 URI 應該只代表 "資源" 的位置。
Representational 表象
資源可以有各種具體的表現形式,比如文本可以有xml
格式,html
格式,json
格式,甚至是二進制格式,圖片可以有PNG
格式,JPEG
格式等。資源的一個具體表現形式,應該在 HTTP 請求的頭信息中用Accept
和Content-Type
字段指定,這兩個字段纔是對 "表現層" 的描述。
State Transfer 狀態轉移
通過 http 動詞來實現資源的狀態轉移,用GET
來請求資源,用POST
來新建資源,用PUT
來更新資源,用DELETE
來刪除資源。
簡明扼要的總結 REST:
-
用 URI 來定位具體的資源
-
用 HTTP 請求的 Content-Type 字段來描述資源的表現形式
-
用 HTTP 動詞來描述對資源的具體操作
RESTful API 設計總結
隨着近年來移動互聯網的發展,各種客戶端出不窮:Web,IOS,Android。因此需要一種機制使得各種客戶端能夠和服務端進行通訊,這就使得 RESTful API 的架構流行起來。RESTful 是 REST(表現層狀態轉化) 的形容詞形式,因此 RESTful API 就可以理解成 “符合 REST 風格的 API”。
格式規範
根據 RFC3986 定義,URL 是大小寫敏感的。所以爲了避免歧義,儘量使用小寫字母。
RESTful API 應具備良好的可讀性,當 url 中某一個片段(segment)由多個單詞組成時,建議使用 -
來隔斷單詞,而不是使用 _
。這主要是因爲,瀏覽器中超鏈接顯示的默認效果是文字並附帶下劃線,如果 API 以_
隔斷單詞,二者會重疊,影響可讀性。
/api/featured-post/ # GOOD
/api/featured_post/ # WRONG
協議
提供給用戶的 API,總是使用 HTTPs 協議。使用 HTTPs 協議還是 HTTP 協議本身和 RESTful API 並無關係,但是這對於提高網站的安全性很重要。
域名
API 應該放在專有域名下,比如https://api.example.com/v1
。也可以簡單地把版本放在 URL 中,比如https://www.example.com/api/v1
版本
API 的版本號應該放在 URL 中:
https://api.example.com/v1/
名詞應該使用複數
所用的名詞往往和數據庫的表名對應,而數據庫的表是一組記錄的集合,因此 URL 中的名詞即表示一組資源的集合,故 URI 中的名詞要使用複數
https://api.example.com/v1/students
https://api.example.com/v1/schools
https://api.example.com/v1/employees
URL 中不能使用動詞
URI 代表着一個資源,是一個實體,應該是名詞,而不要把具體的動作放在 URL 中,對資源的操作應該通過 HTTP 的動詞來實現。
不符合 CRUD 的情況
如果實在無法表示,也可使用動詞,例如 search 沒有對應的 HTTP 方法,可以在路徑中使用 search,更加直觀
http://api.xxx.com/apiv3/search?timestamp=123213218&user_id=4192121&keyword=2134789
。再例如創建了博客網站,如果想要發佈一個博客,可以使用POST /articles/{:id}/publish
用 HTTP 動詞表示對資源的操作
使用 HTTP 協議裏的動詞來實現資源的獲取、刪除、添加等操作
-
GET:從服務器獲取資源
-
POST:在服務器新建一個資源
-
PUT:在服務器更新資源(客戶端提供改變後的完整資源)
-
PATCH:在服務器更新資源(客戶端提供改變的屬性)
-
DELETE:從服務器中刪除資源
GET https://api.example.com/v1/schools # 列出所有學校
POST https://api.example.com/v1/schools # 新建一個學校
GET https://api.example.com/v1/schools/ID # 列出指定學校的信息
DELETE https://api.example.com/v1/schools/ID # 刪除指定學校
GET https://api.example.com/v1/schools/ID/students # 列出指定學校的所有學生
DELETE https://api.example.com/v1/schools/ID/students/ID # 刪除指定學校的指定學生
HTTP 狀態碼
-
200 OK - [GET]:服務器成功返回用戶請求的數據
-
201 CREATED - [POST/PUT/PATCH]:用戶新建或修改數據成功
-
204 NO CONTENT - [DELETE]:用戶刪除數據成功
-
400 INVALID REQUEST - [POST/PUT/PATCH]:用戶發出的請求有錯誤,服務器沒有進行新建或修改數據的操作
-
401 UNAUTHORIZED:表示用戶沒有權限(令牌、用戶名、密碼錯誤)
-
404 NOT FOUND:用戶發出的請求針對的是不存在的記錄,服務器沒有進行操作
-
500 INTERNAL SERVER ERROR:服務器發生錯誤,用戶將無法判斷髮出的請求是否成功
其它
API 的身份認證應該使用 OAuth 2.0 框架
服務器返回的數據格式,應該儘量使用 JSON,避免使用 XML。JSON 有可讀性強,結構緊湊,支持的語言種類多的特點,因此 JSON 是 RESTful API 最常用的返回格式。
本文由 Readfog 進行 AMP 轉碼,版權歸原作者所有。
來源:https://mp.weixin.qq.com/s/CNYL9WQS3_gQijTW_yCnlw