Restful API 的設計

引子

Restful API 是如今比較常見的HTTP API設計方案了。不論是不是真的理解，不少項目組都開始運用restful思想設計API。前幾天部門領導蒞臨指導，更是反覆強調要 restful。姑且認爲他也是通過深刻研究的吧。

優勢和缺點

restful 是一種簡單的設計方案。它認爲網站，或者說後臺服務是對資源的管理，包括建立，更新，獲取和刪除。實際設計的時候，須要對資源進行合理的抽象。

restful 指導原則比較簡單，一切皆是資源，api 就是對資源的管理。那麼問題來了，如何有效的抽象這些資源？ 好比， search 是很是常見的api，如何將它 restful 化呢？

基本原則

restful 認爲一切皆是資源， API 應該是對資源的狀態的轉化。

url 路徑中只應該包含資源標識符

好比，建立訂單，非 restful API 多是這樣的:

/createPO

這個業務中，PO是一種資源，restful 風格的 API 應該應該是

/PO

那麼，如何標誌這個API 是建立 PO 呢？

利用 http method 定義資源狀態轉化

上面的例子，可使用 POST 方法定義建立 PO。

POST /PO

restful 主張用http method來標誌資源狀態的轉化，有下面四種：

• POST 建立

• PUT 更新

• GET 獲取

• DELETE 刪除

因此，對於PO,它的建立，更新，獲取，刪除，API以下

POST /PO
PUT /PO/:id
GET /PO/:id
DELETE /PO/:id

實踐和思考

理論上來說，restful 是讓 API 的設計變得簡單了。抽象資源+狀態轉化。實際中要注意的是對資源的抽象應該在較高的層次，即實際的業務層次。我見過不少的程序員都習慣從數據庫的角度來抽象資源，好比，一個表就對應一個資源。這是沒有意義的，這樣的API只是變相的對數據表的抽象，而非對資源的轉化。由於不少表的數據原本是不該該被 API 操做的，並且，業務實體也不會映射到單一的數據表。說到底，API的用戶，不論是第三方，仍是前臺，它們關心的並非數據表的細節，而是業務實體。

因此，實際上的 POST API，也許並不只是建立一行數據，也許它也同時更新了某些數據，刪除了某些數據，這些均可以依具體業務而定。建立資源並不等於在某個具體的表中插入數據，而是在高層次的業務實體上的建立。

上面的例子，其實實際業務通常不會這麼簡單，好比PO都會從屬於某一個用戶，因此API的結構會是下面這樣,以 PUT 爲例

PUT /user/:userid/PO/:poid

這裏就引伸出一個值得討論的話題，如何設計從屬關係？從業務實體上設計從屬關係可能會遇到一些困難，好比，某些狀況下，父資源的建立可能會依賴子資源的建立。個人建議是，若是開銷不大的話，能夠從新設計一下業務。好比，PO必須從屬於一個user，那麼業務上就規定必須先註冊（建立user）或者登錄，才能下訂單（建立PO）。

遇到困難的時候

有些時候會遇到一些設計上的困難，多是因爲對 restful 的認識不深，或者業務實在太奇葩。若是不牽涉什麼商業機密的話，能夠向社區或者論壇求助。

當項目進度很是緊張的時候，這個時候仍是要以實現功能爲先，避免被指責。:)

總結

技術的變革通常都是爲了提升生產力的，restful的初衷也是。它提倡簡單（理論上講只要業務實體抽象的好就夠了），純粹（每一個資源就四種操做）的 API 設計思想，須要使用者堅持信仰（堅持基本原則），適度靈活。