RESTful API 設計最佳實踐

web api 近幾年變得越來越火，而簡潔的 api 設計在多後端系統互動應用中也變得尤為重要。通常，會使用 restful api 來作為我們的 web api 。本文介紹了幾種簡潔 restful api 設計的最佳實踐。

使用名詞來定義接口

資源

get

put

post

delete

一組資源的uri，比如<code>http://www.waylau.com/resources/</code>

列出 uri，以及該資源組中每個資源的詳細資訊（後者可選）。

使用給定的一組資源替換目前整組資源。

在本組資源中建立/追加一個新的資源。 該操作往往傳回新資源的url。

删除 整組資源。

單個資源的uri，比如<code>http://www.waylau.com/resources/142</code>

擷取 指定的資源的詳細資訊，格式可以自選一個合适的網絡媒體類型（比如：xml、json等）

替換/建立 指定的資源。并将其追加到相應的資源組中。

把指定的資源當做一個資源組，并在其下建立/追加一個新的元素，使其隸屬于目前資源。

删除 指定的元素。

不應該使用動詞：

如果要改變資源的狀态，使用 put, post 和 delete。下面是錯誤的用 get 方法來修改 user 的狀态：

不要混淆名詞的單複數。保持簡單，隻用複數名詞定義所有資源。

用戶端、服務端都需要知道互相之間的通訊格式。這些格式可以定義在 http header 裡面：

content-type：定義了請求格式

accept：定義了接收相應的格式清單

hateoas（hypermedia as the engine of application state）是 rest 架構風格中最複雜的限制，也是建構成熟 rest 服務的核心。它的重要性在于打破了用戶端和伺服器之間嚴格的契約，使得用戶端可以更加智能和自适應，而 rest 服務本身的演化和更新也變得更加容易。 在介紹 hateoas 之前，先介紹一下 richardson 提出的 rest 成熟度模型。該模型把 rest 服務按照成熟度劃分成 4 個層次：

第一個層次（level 0）的 web 服務隻是使用 http 作為傳輸方式，實際上隻是遠端方法調用（rpc）的一種具體形式。soap 和 xml-rpc 都屬于此類。

第二個層次（level 1）的 web 服務引入了資源的概念。每個資源有對應的辨別符和表達。

第三個層次（level 2）的 web 服務使用不同的 http 方法來進行不同的操作，并且使用 http 狀态碼來表示不同的結果。如 http get 方法來擷取資源，http delete 方法來删除資源。

第四個層次（level 3）的 web 服務使用 hateoas。在資源的表達中包含了連結資訊。用戶端可以根據連結來發現可以執行的動作。

從上述 rest 成熟度模型中可以看到，使用 hateoas 的 rest 服務是成熟度最高的，也是推薦的做法。對于不使用 hateoas 的 rest 服務，用戶端和伺服器的實作之間是緊密耦合的。用戶端需要根據伺服器提供的相關文檔來了解所暴露的資源和對應的操作。當伺服器發生了變化時，如修改了資源的 uri，用戶端也需要進行相應的修改。而使用 hateoas 的 rest 服務中，用戶端可以通過伺服器提供的資源的表達來智能地發現可以執行的操作。當伺服器發生了變化時，用戶端并不需要做出修改，因為資源的 uri 和其他資訊都是動态發現的。

下面是一個 hateoas 的例子：

過濾：

排序：

字段選擇:

分頁:

版本号使用簡單的序号，并避免點符号，如2.5等。正确用法如下：

http狀态碼（http status code）是用以表示網頁伺服器 http 響應狀态的3位數字代碼。它由 rfc 2616 規範定義的，并得到 rfc 2518、rfc 2817、rfc 2295、rfc 2774、rfc 4918 等規範的擴充。

在設計 api 處理錯誤時，應該充分使用 http 狀态碼，而不是簡單的抛出個 “500 – internal server error（内部伺服器錯誤）”

所有的異常都應該有個錯誤的 payload 作為映射，下面是一個例子：

<a href="https://github.com/waylau/rest-in-action">《rest 實戰》</a>

<a href="http://martinfowler.com/articles/richardsonmaturitymodel.html">http://martinfowler.com/articles/richardsonmaturitymodel.html</a>

<a href="https://www.crummy.com/writing/speaking/2008-qcon/act3.html">https://www.crummy.com/writing/speaking/2008-qcon/act3.html</a>

<a href="https://en.wikipedia.org/wiki/hateoas">https://en.wikipedia.org/wiki/hateoas</a>

<a href="https://en.wikipedia.org/wiki/list_of_http_status_codes">https://en.wikipedia.org/wiki/list_of_http_status_codes</a>