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
Presentation
Code
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 檔案
Presentation
Code
Script
Code
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

客戶端和伺服器結構
●
滿足 RESTful 的系統必需存在客戶端和伺服器端
●
RESTful 只規範伺服器，和客戶端與伺服器端之
間的通訊協定

能夠利用快取機制增進性能
●
系統內的所有東西都必須定義能否使用快取
●
客戶端可以為首次可快取資源建立本地快取！在
下次 Request 時，客戶會把本地快取版本告訴伺
服器。如果伺服器發現資源沒有改動，便會要求
客戶端使用本地快取的資源。
●
可以省下伺服器 CPU 資源和網路流量（＝省錢）
●
不常變動的物件適合設定為可快取，如網頁界面
●
詳見： HTTP conditional GET

分層式系統

以下內容非常重要，直接影響到閣下未來爆肝度
睡著了的朋友請起來聽講
（謎之聲：睡了的朋友又怎能看到這段文字？）

淺談網路的不穩定性
●
隨時會斷線！往往看起來正常，其實已經斷線
●
使用 API 時，連線可能在信號送達伺服器前斷線
●
也可能在伺服器正要傳回 API 結果時斷線
●
更可能客戶端以為斷線，卻早已成功傳送資訊
●
除非使用同一個 TCP/IP 連線，否則當客戶端先
發出 API1 ，然後再發出 API2 後，在次序錯亂的
情況下，伺服器有可能先收到 API2 ～

無狀態通訊協定
1. 通訊協定具有無狀態性
2. atomic （原子）
3. 足夠完整的資料
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 格式傳回用戶

無狀態通訊協定
1. 通訊協定具有無狀態性
2. atomic （原子性）
3. 足夠完整的資料
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 即可！

足夠完整的資料
每個 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 步是否等於 " 炮二平五 " 。如果是，傳回＂成
功＂給客戶端；如果不是，則傳回錯誤。

重新呼叫
●
在客戶端，任何未成功收到傳回訊息的 API ，只
需要重新呼叫。
●
伺服器端需要懂得處理重覆 API request
●
在建立新物件時，把客戶端時間也放到 API
request 中，讓伺服器能分辦是否收到重覆的
HTTP POST

統一介面
●
所有介面都應該基於物件，而不是行動
●
前述的遊戲檢錢，就是建立
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 屬下建立新的書本

問題時間

RESTful API Design

Recommended

More Related Content

What's hot (20)

Similar to RESTful API Design (20)

More from Amigo 陳兆祥 (13)

RESTful API Design