RESTful API設計規範

restful 是目前最流行的 api 設計規範，用於 web 資料介面的設計。

它的大原則容易把握，但是細節不容易做對。本文總結 restful 的設計細節，介紹如何設計出易於理解和使用的 api。

restful的核心思想就是，客戶端發出的資料+操作指令都是「動詞+賓語」的結構，比如get /articles這個命令，get是動詞，/articles是賓語，動詞通常就有5種http請求方法，對應crud操作，根據 http 規範，動詞一律大寫。

# get：讀取（read） # post：新建（create） # put：更新（update） # patch：更新（update），通常是部分更新

# delete：刪除（delete）

有些客戶端只能使用get和post這兩種方法。伺服器必須接受post模擬其他三個方法（put、patch、delete）。這時，客戶端發出的 http 請求，要加上x-http-method-override屬性，告訴伺服器應該使用哪乙個動詞，覆蓋post方法。

x-http-method-override: put上面**中，x-http-method-override指定本次請求的方法是put，而不是post。

賓語就是 api 的 url，是 http 動詞作用的物件。它應該是名詞，不能是動詞。比如，/articles這個 url 就是正確的，而下面的 url 不是名詞，所以都是錯誤的。

# /getallcars # /createnewcar

# /deleteallredcars

既然 url 是名詞，那麼應該使用複數，還是單數？這沒有統一的規定，但是常見的操作是讀取乙個集合，比如get /articles（讀取所有文章），這裡明顯應該是複數。

為了統一起見，建議都使用複數 url，比如get /articles/2要好於get /article/2。

常見的情況是，資源需要多級分類，因此很容易寫出多級的 url，比如獲取某個作者的某一類文章。

# get /authors/12/categories/2

這種 url 不利於擴充套件，語義也不明確，往往要想一會，才能明白含義。

更好的做法是，除了第一級，其他級別都用查詢字串表達。

# get /authors/12?categories=2

下面是另乙個例子，查詢已發布的文章。你可能會設計成下面的 url。

# get /articles/published

查詢字串的寫法明顯更好

# get /articles?published=true

客戶端的每一次請求，伺服器都必須給出回應。回應包括 http 狀態碼和資料兩部分。

http 狀態碼就是乙個三位數，分成五個類別。

# 1xx：相關資訊 # 2xx：操作成功 # 3xx：重定向 # 4xx：客戶端錯誤

# 5xx：伺服器錯誤

這五大類總共包含100多種狀態碼，覆蓋了絕大部分可能遇到的情況。每一種狀態碼都有標準的（或者約定的）解釋，客戶端只需檢視狀態碼，就可以判斷出發生了什麼情況，所以伺服器應該返回盡可能精確的狀態碼。

api 不需要1xx狀態碼，下面介紹其他四類狀態碼的精確含義。

200狀態碼表示操作成功，但是不同的方法可以返回更精確的狀態碼。

# get: 200 ok # post: 201 created # put: 200 ok # patch: 200 ok

# delete: 204 no content

上面**中，post返回201狀態碼，表示生成了新的資源；delete返回204狀態碼，表示資源已經不存在。

此外，202 accepted狀態碼表示伺服器已經收到請求，但還未進行處理，會在未來再處理，通常用於非同步操作。下面是乙個例子。

}api 用不到301狀態碼（永久重定向）和302狀態碼（暫時重定向，307也是這個含義），因為它們可以由應用級別返回，瀏覽器會直接跳轉，api 級別可以不考慮這兩種情況。

api 用到的3xx狀態碼，主要是303 see other，表示參考另乙個 url。它與302和307的含義一樣，也是"暫時重定向"，區別在於302和307用於get請求，而303用於post、put和delete請求。收到303以後，瀏覽器不會自動跳轉，而會讓使用者自己決定下一步怎麼辦。

下面是乙個例子。

location: /api/orders/123454xx狀態碼表示客戶端錯誤，主要有下面幾種。

5xx狀態碼表示服務端錯誤。一般來說，api 不會向使用者透露伺服器的詳細資訊，所以只要兩個狀態碼就夠了。

get /orders/2 http/1.1

有一種不恰當的做法是，即使發生錯誤，也返回200狀態碼，把錯誤資訊放在資料體裡面，就像下面這樣。

}上面**中，解析資料體以後，才能得知操作失敗。

這張做法實際上取消了狀態碼，這是完全不可取的。正確的做法是，狀態碼反映發生的錯誤，具體的錯誤資訊放在資料體裡面返回。下面是乙個例子。

}api 的使用者未必知道，url 是怎麼設計的。乙個解決方法就是，在回應中，給出相關鏈結，便於下一步操作。這樣的話，使用者只要記住乙個 url，就可以發現其他的 url。這種方法叫做 hateoas。

舉例來說，github 的 api 都在 api.github.com 這個網域名稱。訪問它，就可以得到其他 url。

",
"gists_url"
:"",
"hub_url"
:"",
...}

上面的回應中，挑乙個 url 訪問，又可以得到別的 url。對於使用者來說，不需要記住 url 設計，只要從 api.github.com 一步步查詢就可以了。

hateoas 的格式沒有統一規定，上面例子中，github 將它們與其他屬性放在一起。更好的做法應該是，將相關鏈結與其他屬性分開。

, ]}

}api design, by microsoft azure

RESTful API設計規範

restful api 設計規範

RESTful API 設計規範

Restful API設計規範

RESTful API設計規範

restful api 設計規範

RESTful API 設計規範

Restful API設計規範

相關推薦