RESTful API Design

©©Triton Ho @ Mar's PotatoTriton Ho @ Mar's Potato

RESTful API DesignRESTful API Design

Triton Ho @ Mar's PotatoTriton Ho @ Mar's Potato


特別感謝

● 感謝 Mozilla 借出場地

● 感謝陳兆祥先生幫助活動統籌


大綱

● 個人簡述

● 為什麼要重視 API 設計

● 比較傳統與 API 網頁設計

● RESTful API 設計


大綱

● 個人簡述





個人簡述

● 豐富的火星系統救火經驗

● 喜歡資料庫

● 喜歡貓

● 出沒於 Hong Kong Linux User Group @ FB


大綱

● 個人簡述





為什麼要重視 API 設計

好的 API 設計，

不能讓你考試一百分，升職加薪


但是可以讓你減少爆肝機會

（前題：老闆在你提升工作效率後不再追加工作）


大綱

● 個人簡述





誰需要重視 API 設計

等一下，我是網頁工程師

RESTful API 和我有關係嗎？


傳統網頁流程

Client Server

1. 用戶發出 http://www.abc.com 的 Request

2. 伺服器根據準備 Data 和 Presention logic

PresentationCode

4. 伺服器把 html 丟回用戶

Data

3. 伺服器把 Data 和 Presentation 結合成完整的 html

Result html


可怕的程式碼與數據交錯

● Data 和 Presentation 混合， Presentation 無法單獨 cache ，只要 Data 變動就必須重新產生

● 無法徹底分割 Presentation 、 Business Logic 、和 Data ，影響開發、測試、除錯的協同作業

● 伺服器負責將 Data 和 Presentation 整合（簡稱Data Binding ），消耗伺服器的 CPU 資源


API 網頁工程師的看法

Client Server

1. 用戶發出 http://www.abc.com 的 Request

2. 伺服器回傳 Presentation 文件與 Scripting 檔案

PresentationCode

ScriptCode

3. 用戶端瀏覽器執行 Scripting ，根據指示對 api.opensource.hk 作出 request

4. 伺服器以 json / xml 的格式回傳 Data Data

5. 瀏覽器把 html 和 Data 結合，然後在畫面顯示出來


優點 1 ：客戶端快取節省流量

表面上看起來，原先僅需一次 request 增加為兩次，似乎花了更多的時間與網路流量！

但是，只要負責美工的同事不改變網頁外表。第一個request 伺服器會回答 HTTP 304 Not Modified ，直譯就是：回家吃自己～ Presentation 最近沒改動，用之前的版本吧！

因為網頁的 Presentation 不用每次重傳，可以節省不少網路流量（＝省下錢＄）


優點 2 ：資料與介面分離

現在 Presentation 和 Data 已經徹底分離！

開發和測試 Presentation 的 data mocking 可以使用專門的 mock API 伺服器。

只要準備好 API 與測試資料，前端工程師就能專心工作。前端延誤和後端工程師無關，不必背黑鍋～

可再將執行架構改為 Presentation 在 Apache ， API在 Tomcat 。


優點 3 ：節省伺服器計算資源

可以不在伺服器做的東西，便不要放在伺服器

Data Binding 現在是交給瀏覽器處理，不再是伺服器的工作，省下伺服器的 CPU 計算資源 !

即使未來要支持 IOS ， Android ，只要背後邏輯不變，這些 API 將能全部重覆使用，節省開發時間！


優點４：能重用的伺服器程式

即使未來要支持 IOS ， Android ，只要背後邏輯不變，這些 API 將能全部重覆使用，節省開發時間


大綱

● 個人簡述





先談 RESTful謬誤

server side 需要 stateless

正解： RESTful 只要求 Application Server 是stateless ， Server Side其他部份可以 stateful


要新一代支援 RESTful 的 noSQL 資料庫

正解： RESTful 和資料庫沒直接關係，你可以使用PostgreSQL 、 MySQL 、或 Oracle


一定需要用上 HTTP 的 GET, PUT, POST, DELETE

正解：統一介面 (Uniform interface) 只建議善用HTTP ，使用其他技術實作的統一介面也能滿足RESTful 要求


使用 RESTful 的工程師都找不到女朋友

正解：（這倒有可能是事實）


RESTful 的要求● Client-server （客戶端和伺服器結構）

● Cacheable （能夠利用快取機制增進性能）

● Layered system （分層式系統）

● Stateless protocol （通訊協定具有無狀態性）

● Uniform interface （統一介面）

From Wiki







From Wiki


客戶端和伺服器結構

● 滿足 RESTful 的系統必需存在客戶端和伺服器端

● RESTful 只規範伺服器，和客戶端與伺服器端之間的通訊協定







From Wiki


能夠利用快取機制增進性能● 系統內的所有東西都必須定義能否使用快取

● 客戶端可以為首次可快取資源建立本地快取！在下次 Request 時，客戶會把本地快取版本告訴伺服器。如果伺服器發現資源沒有改動，便會要求客戶端使用本地快取的資源。

● 可以省下伺服器 CPU 資源和網路流量（＝省錢）

● 不常變動的物件適合設定為可快取，如網頁界面

● 詳見： HTTP conditional GET







From Wiki


分層式系統







From Wiki


以下內容非常重要，直接影響到閣下未來爆肝度

睡著了的朋友請起來聽講

（謎之聲：睡了的朋友又怎能看到這段文字？）


淺談網路的不穩定性● 隨時會斷線！往往看起來正常，其實已經斷線

● 使用 API 時，連線可能在信號送達伺服器前斷線

● 也可能在伺服器正要傳回 API 結果時斷線

● 更可能客戶端以為斷線，卻早已成功傳送資訊

● 除非使用同一個 TCP/IP連線，否則當客戶端先發出 API1 ，然後再發出 API2 後，在次序錯亂的情況下，伺服器有可能先收到 API2 ～


無狀態通訊協定

1. 通訊協定具有無狀態性

2. atomic （原子）

3. 足夠完整的資料

4. 重新呼叫






4. 重新呼叫


通訊協定具有無狀態性

RESTful 伺服器端是被允許有狀態的

Application Server 必須是無狀態

RESTful准許把狀態儲存到資料庫中，例如將登入狀態的短期資訊放到短期資料庫 (Redis)

最簡單的程式說法： RESTful禁止使用HttpSession(Java) ， session_start(PHP)


無狀態通訊協定範例1. 用戶發出 http://api.abc.com/user/60321?access-

key=rbo9PUDgx3Bvl5Ij20fYEWct_CfH

2. Application Server 對 access-key 作出解密，得到 Session ID=0x1A6C9C77869EF675

3. Application Server 根據 Session ID ，到 Redis資料庫拿回登入狀態，知道用戶正是 User 60321本人，並且有足夠權限使用這個 API

4. Application Server到 PostgreSQL 資料庫拿資料

5. Application Server 把資料以 JSON 格式傳回用戶




2. atomic （原子性）


4. 重新呼叫


atomic （原子性）

每一個動作都必需是 atomic 。一個完整執行後的API呼叫不能讓伺服器端數據停留在不一致的狀態。

Each action call should be atomic. Any Successful API call should not leave server side in inconsistent state.

另一個說法：你不能使用二個（或以上） API呼叫去完成一個「動作」


不符合 atomic 的範例● 你現在是光明破壞神三的工程師，因為遊戲內有檢錢這個動作，所以有檢錢的 API

/user/60321/single_user_coin_change (POST)

POST_DATA =

{

"change_amount": 100,

"description" : "從怪物 645389890 的屍體上檢錢 ",

"create_time" : "2014-07-05T16:35:46"

}


● 現在主管突然覺得數字網太好賺，想連那部份也自己來賺，要求讓遊戲中的金幣支援轉帳服務

● 主管說：不用新建 API啦，把現有的single_user_coin_change沿用，把「用戶Ａ轉帳到用戶Ｂ」這個動作拆成「從用戶Ａ扣錢」和「把錢加到用戶Ｂ」二個動作。

看到不符合的地方嗎？


● 後果是：新的轉帳功能推出後，有用戶發現轉帳時金幣不翼而飛！

● 因為用戶完成「從用戶Ａ扣錢」後，遇上藍畫面或是網絡問題，沒法完成「把錢加到用戶Ｂ」動作。


前端工程師想出了解決方案：轉帳前先把這記錄存放在客戶端硬碟

● 程式重新啟動時發現未完成的轉帳記錄時，客戶端需要：

● 先問伺候器，轉帳過程是停在那一步驟

● 從當掉的步驟重來

不過對於硬碟故障的客戶，這方案沒用！


後端工程師想出了另一個解決方案：藉 POST_DATA中的 description 作配對。

● 找出所有扣了Ａ的錢而沒有為Ｂ加錢的轉帳，然後作出數據回復

● 需要定期掃瞄資料庫中的所有記錄，引起嚴重效能問題

掃瞄程式超級難寫，後端工程師肝病可能性大升


符合 atomic 的範例● 建立新的 API

RESTful API /user/{user_id}/coin_transfer_transaction (POST)

POST_DATA =

{

"from_user_id": "60321",

"to_user_id": "89072",

"amount": 100,

"description" : "從用戶 60321轉帳到用戶 89072"

"create_time" : "2014-07-05T16:35:46"

}

當用戶當機或網路斷線，再重新執行一次 API即可！






4. 重新呼叫


足夠完整的資料

每個 API呼叫時都需要向伺服器提供足夠完整的資料

Each API call should provide sufficient information for server side to process.


常見錯誤

● 你不應該假設伺服器知道「現在狀態」

錯誤例子：玩中國象棋時，單純把用戶端指令用「炮二平五」來回傳給伺服器


不完整的資料範例1. 在紅方第 31步行動時，紅方發出「炮二平五」指令

2. 這時網絡某個路由器發生嚴重錯亂，把「炮二平五」的網絡封包送到火星

3. 紅方電腦等 10秒後沒有收到伺服器回應，以為網絡錯誤，於是再發出「炮二平五」指令，這個封包經由正常的路由器，所以 1秒內就被傳送到伺服器

4. 10 分鐘後，送往火星的錯誤封包終於被送到伺服器

5. 這時已經到達第 55步紅方行動，剛好紅方有炮棋在二線，伺服器沒法知道這是第 31步時的封包，並且以為這是第 55步的指令，因此執行「炮二平五」的指令，並且拒絕之後用戶真正第 55步的指令


● RESTful 的「足夠資料」，在中國象棋中最簡單實現的方法便是把每隻棋子的位置以及棋局的最後更改時間，在「炮二平五」的指令中同時傳給伺服器。

● 這樣伺服器便有足夠資料去分辨第 31步時路經火星的封包。（因為棋局狀況和最後更改時間不符合）


● 不過，每次都把完整狀態丟來丟去是白痴，因為這將會大量消耗網絡封包

● 如果這是梭哈遊戲，你有機會可以攔截封包，事先得知對手蓋牌，有資安疑慮！

所以：基於網路效能和資安考量， API所用的資料可以放在伺服器， API 只需說明正在引用那份資料。


完整的資料範例/chinese_chess_game/{game_id} (PUT)

PUT_DATA =

{

"step_id" : 31

"action" : "炮二平五 "

}

伺服器收到這個 Request 時，會從短期資料庫中拿出第 31步的棋局。

如果第 31步已經被執行，伺服器會檢查已經存在的第 31步是否等於 "炮二平五 " 。如果是，傳回＂成功＂給客戶端；如果不是，則傳回錯誤。






4. 重新呼叫


重新呼叫

● 在客戶端，任何未成功收到傳回訊息的 API ，只需要重新呼叫。

● 伺服器端需要懂得處理重覆 API request

● 在建立新物件時，把客戶端時間也放到 API request中，讓伺服器能分辦是否收到重覆的HTTP POST







From Wiki


統一介面● 所有介面都應該基於物件，而不是行動

● 前述的遊戲檢錢，就是建立single_user_coin_change這個物件

● 一個物件正常有４種行動：查詢，更改，誕生，刪除

●查詢：一般使用 HTTP GET method●更改：一般使用 HTTP PUT method●誕生：一般使用 HTTP POST method●刪除：一般使用 HTTP DELETE method


統一介面範例/v3/user/1234/book/54389● v3 = 使用第三版本的 /user/1234/book/54389 API● user/1234/book/54389 = 這是關於使用者 1234屬下的書

本 54389

– GET = 取得書本內容– PUT = 更改書本內容– DELETE = 刪除書本紀錄

/v3/user/1234/book/● GET = 取得使用者 1234屬下的書本● POST = 在使用者 1234屬下建立新的書本


問題時間

Technology

RESTful API Design