技術觀念 | 淺談分散式系統 - 深入理解 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

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

Uncleaned URL	Clean URL
http://example.com/index.php?page=name	http://example.com/name
http://example.com/about.html	http://example.com/about
http://example.com/index.php?page=consulting/marketing	http://example.com/consulting/marketing
http://example.com/products?category=12&pid=25	http://example.com/products/12/25
http://example.com/cgi-bin/feed.cgi?feed=news&frm=rss	http://example.com/news.rss
http://example.com/services/index.jsp?category=legal&id=patents	http://example.com/services/legal/patents
http://example.com/kb/index.php?cat=8&id=41	http://example.com/kb/8/41
http://example.com/index.php?mod=profiles&id=193	http://example.com/profiles/193
http://en.wikipedia.org/w/index.php?title=Clean_URL	http://en.wikipedia.org/wiki/Clean_URL

實現：

通過模式匹配進行 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

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