Restful架構思想理解

著做權歸做者全部。
商業轉載請聯繫做者得到受權，非商業轉載請註明出處。
做者：覃超
連接：http://www.zhihu.com/question/27785028/answer/48096396
來源：知乎

我以爲問題很好，我本身去年創業的時候去學習REST和嘗試着設計RESTful API，一直以爲它的文檔晦澀難懂，國內也沒有找到太好文章。後來一年內反覆琢磨了好幾遍，和FB+Square的朋友討論過好幾回，有了一個比較清晰的總結。分享以下：

@Ivony 老師的一句話歸納很精闢：
URL定位資源，用HTTP動詞（GET,POST,DELETE,DETC）描述操做。

--- 簡潔版 ---

0. REST不是"rest"這個單詞，而是幾個單詞縮寫。但即便那幾個單詞說出來，也沒法理解在說什麼 -_-!! （不是要貶低人，是我本身也理解困難）；
1. REST描述的是在網絡中client和server的一種交互形式；REST自己不實用，實用的是如何設計 RESTful API（REST風格的網絡接口）；
2. Server提供的RESTful API中，URL中只使用名詞來指定資源，原則上不使用動詞。「資源」是REST架構或者說整個網絡處理的核心。好比：

http://api.qc.com/v1/newsfeed: 獲取某人的新鮮; 
http://api.qc.com/v1/friends: 獲取某人的好友列表;
http://api.qc.com/v1/profile: 獲取某人的詳細信息;

3. 用HTTP協議裏的動詞來實現資源的添加，修改，刪除等操做。即經過HTTP動詞來實現資源的狀態扭轉：

GET 用來獲取資源，
POST 用來新建資源（也能夠用於更新資源），
PUT 用來更新資源，
DELETE 用來刪除資源。

好比：

DELETE  http://api.qc.com/v1/friends: 刪除某人的好友 （在http parameter指定好友id）
POST  http://api.qc.com/v1/friends: 添加好友
UPDATE  http://api.qc.com/v1/profile: 更新我的資料

禁止使用： GET  http://api.qc.com/v1/deleteFriend

圖例：
<img src="https://pic1.zhimg.com/7405939b62a73f28846533de08db3a80_b.jpg" data-rawwidth="1328" data-rawheight="702" class="origin_image zh-lightbox-thumb" width="1328" data-original="https://pic1.zhimg.com/7405939b62a73f28846533de08db3a80_r.jpg">
4. Server和Client之間傳遞某資源的一個表現形式，好比用JSON，XML傳輸文本，或者用JPG，WebP傳輸圖片等。固然還能夠壓縮HTTP傳輸時的數據（on-wire data compression）。
5. 用 HTTP Status Code傳遞Server的狀態信息。好比最經常使用的 200 表示成功，500 表示Server內部錯誤等。

主要信息就這麼點。最後是要解放思想，Web端再也不用以前典型的PHP或JSP架構，而是改成前段渲染和附帶處理簡單的商務邏輯（好比AngularJS或者BackBone的一些樣例）。Web端和Server只使用上述定義的API來傳遞數據和改變數據狀態。格式通常是JSON。iOS和Android同理可得。因而可知，Web，iOS，Android和第三方開發者變爲平等的角色經過一套API來共同消費Server提供的服務。


--- 詳細版 ---

先說REST名稱
REST：REpresentational State Transfer = 直接翻譯：表現層狀態轉移。這個中文直譯常常出如今不少博客中。尼瑪誰聽得懂「表現層狀態轉移」？這是人話嗎？
首先，之因此晦澀是由於前面主語被去掉了，全稱是 Resource Representational State Transfer：通俗來說就是：資源在網絡中以某種表現形式進行狀態轉移。分解開來：

Resource：資源，即數據（前面說過網絡的核心）。好比 newsfeed，friends等；
Representational：某種表現形式，好比用JSON，XML，JPEG等；
State Transfer：狀態變化。經過HTTP動詞實現。

REST的出處
Roy Fielding的畢業論文。這哥們參與設計HTTP協議，也是Apache Web Server項目（惋惜如今已是 nginx 的天下）的co-founder。PhD的畢業學校是 UC Irvine，Irvine在加州，有着充裕的陽光和美麗的海灘，是著名的富人區。Oculus VR 的總部就坐落於此（虛擬現實眼鏡，被FB收購，CTO爲Quake和Doom的做者 John Carmack）。
衆說周知，論文都是晦澀難懂的。當年在CMU讀書的時候，不少課程都會安排每週兩篇的Paper review。如今回想起來每次寫Paper review都是我最爲痛苦的時候。REST這篇博士論文毫無疑問更甚。
論文地址： Architectural Styles and the Design of Network-based Software Architectures
REST章節： Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)
REST那章我初讀了，整個論文沒有讀完 =_=
<img src="https://pic3.zhimg.com/11cdfc60bde58e8545bafe42f0af79ca_b.jpg" data-rawwidth="500" data-rawheight="375" class="origin_image zh-lightbox-thumb" width="500" data-original="https://pic3.zhimg.com/11cdfc60bde58e8545bafe42f0af79ca_r.jpg">
RESTful API
實用的是如何正確地理解 RESTful架構和設計好RESTful API。

首先爲何要用RESTful結構呢？
你們都知道"古代"網頁都是前端後端融在一塊兒的，好比以前的PHP，JSP等。在以前的桌面時代問題不大，可是近年來移動互聯網的發展，各類類型的Client層出不窮，RESTful能夠經過一套統一的接口爲 Web，iOS和Android提供服務。另外對於廣大平臺來講，好比Facebook platform，微博開放平臺，微信公共平臺等，它們不須要有顯式的前端，只須要一套提供服務的接口，因而RESTful更是它們最好的選擇。在RESTful架構下：
<img src="https://pic2.zhimg.com/06ee404783540f0af299042057738a99_b.jpg" data-rawwidth="550" data-rawheight="250" class="origin_image zh-lightbox-thumb" width="550" data-original="https://pic2.zhimg.com/06ee404783540f0af299042057738a99_r.jpg">
Server的API如何設計才知足RESTful要求?
首先是簡潔版裏面的那幾點。外加一些附帶的 best practices：
1. URL root:

https://example.org/api/v1/*
https://api.example.com/v1/*

2. API versioning:
能夠放在URL裏面，也能夠用HTTP的header：

/api/v1/

3. URI使用名詞而不是動詞，且推薦用複數。
BAD

• /getProducts
• /listOrders
• /retrieveClientByOrder?orderId=1

GOOD

• GET /products : will return the list of all products
• POST /products : will add a product to the collection
• GET /products/4 : will retrieve product #4
• PATCH/PUT /products/4 : will update product #4

4. 保證 HEAD 和 GET 方法是安全的，不會對資源狀態有所改變（污染）。好比嚴格杜絕以下狀況：

GET /deleteProduct?id=1

5. 資源的地址推薦用嵌套結構。好比：

GET /friends/10375923/profile
UPDATE /profile/primaryAddress/city

6. 警戒返回結果的大小。若是過大，及時進行分頁（pagination）或者加入限制（limit）。HTTP協議支持分頁（Pagination）操做，在Header中使用 Link 便可。
7. 使用正確的HTTP Status Code表示訪問狀態： HTTP/1.1: Status Code Definitions
8. 在返回結果用明確易懂的文本（String。注意返回的錯誤是要給人看的，避免用 1001 這種錯誤信息），並且適當地加入註釋。
9. 關於安全：本身的接口就用https，加上一個key作一次hash放在最後便可。考慮到國情，HTTPS在無線網絡裏不穩定，可使用Application Level的加密手段把整個HTTP的payload加密。有興趣的朋友能夠用手機連上電腦的共享Wi-Fi，而後用Charles監聽微信的網絡請求（發照片或者刷朋友圈）。
若是是平臺的API，能夠用成熟可是複雜的OAuth2，新浪微博這篇： 受權機制說明 各端的具體實現 如上面的圖所示，Server統一提供一套RESTful API，web+ios+android做爲同等公民調用API。各端發展到如今，都有一套比較成熟的框架來幫開發者事半功倍。