KSDG 20150108 Mobile API Design Principles

App的幕後功臣 – 談談API設計基本原則�

KKBOX/MOPCON/KSDG� ericpi�

關於我 – 畢瑄易 (ericpi)�

•  KKBOX COO Room Manager •  Kaohsiung Software Developer Group (KSDG) organizer

•  Mobile/Open/Platform CONference (MOPCON) co-founder & 2012/2013/2014 staff

•  Code For Kaohsiung (CfK) Staff

這兩天開發者都在評論…�

很多人提到該購票網站一次把頁面噴出來的做法…�

明明現代 Web / App 都大量在搞不同資訊分段拿的伎倆�

API是在幹什麼的?�

3G/4G/WiFi� Internet�

IDC/Cloud Server�

3rd Party Service�

API是在幹什麼的?�

App/Web�

Internet�

Your Service�

3rd Party Service�

API

API是在幹什麼的?�

App/Web�

Internet�

Your Service�

3rd Party Service:� Facebook, Twitter…blah�

網路是很危險地�

3G/4G/WiFi� Internet�

IDC/Cloud Server�

3rd Party Service�

[行前說明]�

RFC 2616�

RFC 2616� Hypertext Transfer Protocol -- HTTP/1.1�

如果不遵循標準, 你跟 IE6 有什麼不一樣?!�

已退休, 可以不 要再捅我了嗎?

十之八九 App 都會用 Web API�

十之八九 App 都會用 Web API� •  stateless  protocol� •  scalability� •  availability�

RFC7230 � HTTP/1.1: Message Syntax and Routing - low-level message parsing and connection management

RFC7231 � HTTP/1.1: Semantics and Content - methods, status codes and headers

RFC7232

� HTTP/1.1: Conditional Requests - e.g., If-Modified-Since

RFC7233 � HTTP/1.1: Range Requests - getting partial content

RFC7234 � HTTP/1.1: Caching - browser and intermediary caches

RFC7235 � HTTP/1.1: Authentication - a framework for HTTP authentication�

正題開始, 先來看個小例子�

GET http://you-app-backend.com/login?subscriber_id=123456789�

GET http://you-app-backend.com/login?user=ericpi-demo&pass=qwert12345�

POST http://you-app-backend.com/login      user=ericpi-demo&pass=qwert12345�

POST http://you-app-backend.com/login      user=ericpi-demo&pass=fmq+2n+9RbtROzrcRFhWXA==�

POST http://you-app-backend.com/login      user=ericpi-demo&pass=fmq+2n+9RbtROzrcRFhWXA==�

DES ECB 雙向 加解密演算法

POST http://you-app-backend.com/login      user=ericpi-demo&pass=iloVeyOYO�

難道我喜歡瑤瑤 也要告訴你嗎?

別說這個, 你聽過...�

別說這個, 你聽過...� hash 嗎?�

POST http://you-app-backend.com/login      user=ericpi-demo&pass=327bc4e22b649d47c4546a3ec93f376b�

那試試看MD5好了?

哭哭…�

POST http://you-app-backend.com/login      user=ericpi-demo&pass=0992d82e56834fc7f9647d1783772144�

那試試看兩倍 MD5!!!

兩倍哭哭…�

POST http://you-app-backend.com/login      user=ericpi-demo&pass=137245b801f93aada36b442a5b5bae556799aa9f�

聽說 SHA1  比較厲害!!!

哭哭三次不用錢…�

用 Google 就可以黑… 是要逼死誰…�

HMAC (Hash-based Message Authentication Code)�

     HMAC-MD5      HMAC-SHA1�

光講到這邊, Play/iTunes Store 上的 App 已經倒滿地...�

但今天不是 TDOH 聚會啊啊啊…�

API 設計最主要需要管理�

•  資料� •  流程�

請善用工具釐清設計思路�

API Design 有很多參考資料/書�

•  Vinay Sahni - Best Practices for Designing a Pragmatic RESTful API� – http://goo.gl/OTNGdW�

•  Apigee eBook� – http://goo.gl/S9wA7F�

�

API Design 有很多參考資料/書�

•  3scale eBook� – http://goo.gl/oEdwCv�

•  Build Apis You Won`t Hate� – http://goo.gl/5aaLbZ�

•  Coimotion Hack & Go� – http://goo.gl/o9zRzK�

那今天就借用各家的重點�

Vinay Sahni: Key requirements for the API�

•  It should use web standards where they make sense�

•  It should be friendly to the developer and be explorable via a browser address bar�

•  It should be simple, intuitive and consistent to make adoption not only easy but pleasant�

•  It should provide enough flexibility to power majority of the Enchant UI�

•  It should be efficient, while maintaining balance with the other requirements�

簡單說�

•  長得正� •  要對阿宅友善� •  互動性與彈性好� •  可維護性佳�

跟找女朋友 條件差不多

簡單條列設計原則�

•  Restful API� •  獨立的 API 域名 & 相關 redirect� •  合理的endpoint結構(&命名)� •  納入版本控制� •  資訊過濾、排序、限制、分頁等基本參數�

簡單條列設計原則�

•  尋求標準上的解法� – 請愛用 JSON or XML� – HTTP protocol� – 請愛用 https� – OAuth2�

•  例外與錯誤要講清楚� – HTTP status code�

•  Github 403 Forbidden => 404 Not Found� –  Error response�

•  把資源類內容也納入API�

THANKS� 官方網站� http://mopcon.org/� � 粉絲群� http://fb.me/mopcon�