技術觀念 | 淺談分散式系統 - 深入理解 REST

REST 是 Web Service 的一種實踐方式，是一種 Web Service 架構風格。它與SOAP 不同，儘管SOAP 也常被用於構建Web Service，但SOAP 本身與傳輸協議無關，可以是HTTP（web service），也可以是SMTP，TCP 甚至FTP，這種獨立性必然會帶來設計的複雜性，降低它的可用性和易用性。

與 SOAP-based Web Service 不同，REST 是一種架構風格，不是標準協議。在實現RESTful 風格的API 時會用到HTTP，URI，JSON，和XML 等其它web 標準，REST 只提供架構的理念和約定（Architectural constraints），有時候儘管有些Web Service 並沒有完全遵從REST 的架構約束，也同樣會被稱為RESTful API。

REST（2000s） 就是為 Web Service 而生的，簡潔、易用、易擴展！​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​‌‌​‌‌‌​​‌‌​‌‌‌‌​‌‌​‌‌​​​‌‌​‌‌‌‌​‌‌​​‌‌‌​‌‌‌‌​​‌​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​​​​​‌‌​​‌​​​‌‌​​​​​​‌‌​​​​​​‌‌​​‌‌​​‌‌​​​​​​‌‌​​‌‌​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌​‌​​‌‌‌​​‌

REST 到底什麼呢？

REST Representational State Transfer (REST)，這個術語在字面上不直觀，不好理解，什麼是 Representational，表徵的誰？ State 是誰的 State？

先說 Representation，可以解釋為表徵，象徵，代理，通俗的說就是符號，不是本體。這背後是一個很深刻的哲學問題，有興趣的同學可以看一下《皮爾斯：論符號》。人類生活在一個表徵的世界，概念的世界，符號的世界，我們口中的月亮、玉盤、太陰、Moon，都與那個圍繞著地球旋轉的星球有關，但指向月亮的手不是月亮，它們僅僅是指代那個星體的符號！但是在現實生活中，在各種各樣的社會活動中，我們需要的恰恰是 Representation，而不是 Objectivity！比如，一個人去銀行申請抵押貸款，業務員需要他提供資產證明（Representation），而不是資產實物。

如想更了解可以參考技術觀念 | REST & RESTful 是什麼？​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​‌‌​‌‌‌​​‌‌​‌‌‌‌​‌‌​‌‌​​​‌‌​‌‌‌‌​‌‌​​‌‌‌​‌‌‌‌​​‌​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​​​​​‌‌​​‌​​​‌‌​​​​​​‌‌​​​​​​‌‌​​‌‌​​‌‌​​​​​​‌‌​​‌‌​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌​‌​​‌‌‌​​‌

同樣的道理，在web 事務/服務中，用戶並不關心資源實體是什麼，它可能是xml 文件，也可能是資料表，可能是字符串，也可能是二進制，這都不重要，因為用戶只關心它的Representation，它的表徵物。在 REST 中，資源實體被最終表徵為 json/xml 或者字符串！用戶通過 RESTful 請求以 transfer state 的形式表徵資源實體的增刪改查！

​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​‌‌​‌‌‌​​‌‌​‌‌‌‌​‌‌​‌‌​​​‌‌​‌‌‌‌​‌‌​​‌‌‌​‌‌‌‌​​‌​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​​​​​‌‌​​‌​​​‌‌​​​​​​‌‌​​​​​​‌‌​​‌‌​​‌‌​​​​​​‌‌​​‌‌​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌​‌​​‌‌‌​​‌

“Web resources” 起初是用來指代web 中的文檔/文件（HTML，js,css,image），現在它的涵義變得更加廣泛和抽象，任何可以被請求的內容實體（如，字符串， XML，JSON…）都可以稱之為Web 資源。

Clean URLS 簡單接口的設計

Clean URLs, also sometimes referred to as RESTful URLs, user-friendly URLs, or search engine-friendly URLs, are Uniform Resource Locators (URLs) intended to improve the usability and accessibility of a website or web service by being immediately and intuitively meaningful to non-expert users.

提高 web 接口的可用性、易用性、易理解性，URL 在概念上要簡單、直接，結構上更能反映訊息的資料結構，而不是訊息在服務器中的存儲結構。​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​‌‌​‌‌‌​​‌‌​‌‌‌‌​‌‌​‌‌​​​‌‌​‌‌‌‌​‌‌​​‌‌‌​‌‌‌‌​​‌​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​​​​​‌‌​​‌​​​‌‌​​​​​​‌‌​​​​​​‌‌​​‌‌​​‌‌​​​​​​‌‌​​‌‌​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌​‌​​‌‌‌​​‌

SEO：search engine optimization。

URL 通常包括資源路徑、名稱和訪問參數，訪問參數中常常會包含一些含糊的、無關的元訊息，比如：

1

http://example.com/personal?country=taiwan&province=taipei&name=morose&id=666

訪問參數中訊息是隔離的、含糊的，甚至是冗餘的。
如果修改為：​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​‌‌​‌‌‌​​‌‌​‌‌‌‌​‌‌​‌‌​​​‌‌​‌‌‌‌​‌‌​​‌‌‌​‌‌‌‌​​‌​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​​​​​‌‌​​‌​​​‌‌​​​​​​‌‌​​​​​​‌‌​​‌‌​​‌‌​​​​​​‌‌​​‌‌​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌​‌​​‌‌‌​​‌

1

http://example.com/personal/taiwan/taipei/morose/666

就會顯得簡潔、清晰多了。

實現：

• 通過模式匹配進行 URL 映射（mapping）
• URL 重寫（rewriting）

什麼是 WOA？

建議先看此篇文章了解什麼是SOA，技術觀念 | 淺談分散式系統 - 服務的本質與 SOA​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​‌‌​‌‌‌​​‌‌​‌‌‌‌​‌‌​‌‌​​​‌‌​‌‌‌‌​‌‌​​‌‌‌​‌‌‌‌​​‌​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​​​​​‌‌​​‌​​​‌‌​​​​​​‌‌​​​​​​‌‌​​‌‌​​‌‌​​​​​​‌‌​​‌‌​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌​‌​​‌‌‌​​‌

• WOA：Web-oriented architecture
• SOA：Service-oriented architecture

面向Web架構（Web Oriented Architecture），面向服務架構（SOA）的延伸。
WOA 是從 SOA 衍生出來的概念，可以簡單地理解為基於 Web 的 SOA。

「WOA = SOA + WWW + REST」

The WOA Stack:​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​‌‌​‌‌‌​​‌‌​‌‌‌‌​‌‌​‌‌​​​‌‌​‌‌‌‌​‌‌​​‌‌‌​‌‌‌‌​​‌​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​​​​​‌‌​​‌​​​‌‌​​​​​​‌‌​​​​​​‌‌​​‌‌​​‌‌​​​​​​‌‌​​‌‌​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌​‌​​‌‌‌​​‌

• Distribution (HTTP，feeds)
• Composition（Hypermediea， Mashups）
• Security（OpenID，SSL）
• Data Portability（XML，RDF）
• Data Representation（ATOM，JSON）
• Transfer Methods（REST，HTTP，BitTorrent）

最佳實踐

RESTful API 設計最佳實踐可參考：
Vinay Sahni：Best Practices for Designing a Pragmatic RESTful API

1. 版本（Versioning）：應該將API的版本號放入URL，https://api.example.com/v1/。另一種做法是，將版本號放在HTTP頭訊息中，但不如放入URL方便和直觀。 Github採用這種做法。
2. 路徑（Endpoint）: 表示API的具體網址。
3. HTTP 動詞： GET、POST、PUT、PATCH、DELETE
4. 過濾訊息（Filtering）
   • ?limit=10：指定返回記錄的數量
   • ?offset=10：指定返回記錄的開始位置。
   • ?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
   • ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
   • ?animal_type_id=1：指定篩選條件
5. 狀態碼（Status Codes）
6. 錯誤處理（Error handling）
7. 返回結果
8. Hypermedia API：Hypermedia as the engine of application state (HATEOAS)
9. 其他：認證 OAuth 2.0

​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​‌‌​‌‌‌​​‌‌​‌‌‌‌​‌‌​‌‌​​​‌‌​‌‌‌‌​‌‌​​‌‌‌​‌‌‌‌​​‌​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​​​​​‌‌​​‌​​​‌‌​​​​​​‌‌​​​​​​‌‌​​‌‌​​‌‌​​​​​​‌‌​​‌‌​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​​‌​‌​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌​‌​​‌‌‌​​‌

註：以上參考了
漫谈分布式系统中的技术 —— 从 IPC/RPC，SOA，Web Service/REST 到 micro services（微服务）
RESTful API设计 最佳实践。