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