整理一下目前為止我對 REST 的理解
假的 REST 介面
很多人看到 REST 反應就是，利用 http 動詞，處理資源, 隨便看看就明白了。
這種人很容易就寫出這樣一種介面，所有的請求統一返回 200，body 中有，success, message, data, 大家的實現不同，但是大致就是這麼個意思。
隨處也都能看到這樣的討論，比如這裡。
理解 REST
我們以一個簡單的例子開始，假設我們需要寫一套api，功能包括了使用者，商品，訂單，供應商。
資源
寫 REST 介面，首先需要明白資源這個概念，所有的東西都是資源，我們始終是在操作資源，當然資源需要是個名詞。
於是我們定義出這樣一些資源，users, products, orders, vendors。注意這裡是複數，因為既然是資源，肯定是一堆，是個集合。單複數的概念還是很重要的。
狀態碼
狀態碼是很重要的，是有意義的，客戶端是需要根據狀態碼做判斷的。比如201表示資源被建立了；204 表示請求成功了，但是並沒有什麼資訊需要返回，body 當然是空；202 表示伺服器接受了請求，但是還未處理，響應中應該包含相應的指示資訊，告訴客戶端該去哪裡查詢這次處理是否真正完成了等等。
你可能會遇到一些同事說它判斷不了狀態碼，一定要解析body，body中需要一個欄位表示是否成功...等等，那麼你需要做的是跟他講道理，讓他看看 http 協議。
有用的連結 https://httpstatuses.com/
處理資源
有了資源，我們就會需要對資源進行增刪改查，對應到 http 的動詞，就是 post，delete，put/patch，get。
以一個商品資源為例
| http 動詞 | url | 返回狀態碼 | 描述 |
|---|---|---|---|
| post | /api/products | 201 | 建立一個商品 |
| get | /api/products | 200 | 獲取商品列表 |
| get | /api/products/{id} | 200 | 獲取某個商品資訊 |
| put | /api/products/{id} | 200 / 204 | 完整的替換某個商品 |
| patch | /api/products/{id} | 200 / 204 | 部分更新某個商品 |
| delete | /api/products/{id} | 204 | 刪除某個商品 |
可參考 rfc7231
第一個問題
使用者，商品，訂單，供應商 每個都是獨立的資源，那麼如果我有一個訂單詳情頁面，顯示哪個使用者買的什麼商品，買的誰的商品，什麼時間買的。也就是同時獲取了4個資源的資訊，難道要請求4次嗎？
比如訂單id為10,使用者id為1，商品id為5，供應商id為2。
- get /api/orders/10
- get /api/products/5
- get /api/vendors/2
- get /api/users/1
或者是另一種解決辦法，訂單詳情預設包含了它的商品，使用者，供應商資訊？
- get /api/orders/10
這樣是請求了一次，但是如果客戶端只需要訂單資訊，我為什麼要進行額外的查詢，返回額外的資訊。
完美的方案
首先，介面的設計應該站在資源的角度，關心的不是頁面如何顯示，而是客戶端需要什麼資源，而需要什麼當然只能是客戶端自己決定。其次資源之間是有關聯的，我們要利用資源之間的關係，於是可能是下面這樣：
get /api/orders/10?include=user,vendor,product意思就是我需要10號訂單的資料，同時需要訂單相關的使用者，供應商，商品資訊。注意這裡是單數，表示其相關的單個資源。
資料格式
有了上面完美的方案，但是資源的資料到底是什麼樣的，又要怎麼巢狀呢？先參考一下這裡。
對於資源來說，肯定需要一個統一的結構，也方便我們巢狀。我們先理解一個簡單好用的json結構。
{
"data": {...}
"meta": {...}
}data 中是這個資源的資料，meta 可選，是資源之外，其他的一些資訊，比如分頁。對於巢狀的資源同樣也是這樣。那麼對於上面的請求，響應應該是下面這樣。
get /api/orders/10?include=user,vendor,product
{
"data": {
"id": 10,
"title": 一個訂單,
...
"product": {
"data": {
"id": 5,
"price": 15
...
}
}
"user": {
"data": {
"id": 1,
"name": "foo"
...
}
}
"vendor": {
"data": {
"id": 2,
"name": "bar"
...
}
}
}
}
再舉個例子
我的訂單列表,
get /api/user/orders?include=product,vendor
{
"data": [
{
"id": 1,
"title": 一個訂單,
...
"product": {
"data": {
"id": 5,
"price": 15
...
}
}
"vendor": {
"data": {
"id": 2,
"name": "bar"
...
}
}
},
...
],
"meta": {
"pagination": {
"total": 60,
"count": 15,
"per_page": 15,
"current_page": 1,
"total_pages": 4,
"links": {
"next": "http://foobar/api/user/orders?page=2"
}
}
}
}
利用好資源的關係和巢狀我們再補充幾個介面
| 動詞 | url | 描述 | includes |
|---|---|---|---|
| get | /api/vendors/{id}/products | 獲取某個供應商的所有商品 | vendor |
| get | /api/vendors/{id}/products/{id} | 獲取某個供應商的某個商品 | vendor |
| get | /api/vendors | 獲取供應商列表 | products |
| get | /api/user/orders | 我的訂單列表 | vendor,products |
| get | /api/users/{id}/orders | 某個使用者的訂單列表 | vendor,products |
注意最後兩個，這裡是參考了 github，用單數的 user 表示當前使用者，因為我們如果有token，伺服器就知道我們是誰。
當然這裡只是個例子，真實業務我們可能並不能檢視別人下的訂單，
第二個問題
我們下了一個訂單，可能會伴隨很多狀態，待付款，已付款，已發貨，已收貨，已取消等等，如何設計api呢？
其實一開始大家很可能會這麼寫
patch /api/orders/{id}/pay 對某個訂單付款
patch /api/orders/{id}/cancel 取消某個訂單這樣或許可以，但是我們引入了動詞，有沒有更好的方法呢？
其實我們始終是在更新訂單狀態
patch /api/orders/{id}
body status: paid,canceled或許可以這樣，對於資源來說我們就是要把訂單的狀態改為paid或者canceled。但是對於每個狀態，提交的引數和要處理的資料可能有很大的不同，難道都寫在一個方法裡？
$status = $request->get('status');
$method = camel_case('patch_'.$status);
return $this->$method($order);介面是一個，但是我們接受到請求只有依然是可以進行介面分發的，類似上面這樣。
put 和 patch 的關係
兩個方法都是更新資源，而且冪等的，但是 put 是整個替換資源，首先需要判斷必填項，然後根據請求替換這個資源。patch 是提交什麼更新什麼。
第二 put 是可以建立資源的，但是一般只存在於客戶端可以指定資源id的情況下
put /api/orders/100更新資源id為100的資源，如果不存在則建立。建立的話返回201，更新的話返回200。這種情況很少見，因為現在基本上都是伺服器生成id。所以對於我們平時處理的業務，其實大部分是 patch。
版本區分
有了 api 當然需要區分版本，因為使用時需要更新的。
那麼用什麼來區分版本其實大體上有兩種
/api/v1/orders
/api/v2/orders或者利用 header
/api/orders
Accept: application/vnd.foobar.v1+json
Accept: application/vnd.foobar.v2+json一些教程裡面覺得放在url上更直觀，比如阮一峰的教程，很多人也用 github 作為例子。
但是其實你看看 github api 的第一頁，https://developer.github.com/v3/, github 及 其他一些的 rest 教程都是推薦第二種的。
總結
上面是我的個人理解，目前基本是按照這個思路實現的介面，但是依然也有很多地方覺得不完美，不規範。歡迎指正和討論
本作品採用《CC 協議》，轉載必須註明作者和本文連結