# From KKBOX Open API to JavaScript SDK - Vincent Chiang

{%hackmd dh921X26R26y_elFAEP5yg %}

###### tags: `jsdc2018`

---
Slide: http://slides.com/zaoldyeck/sdk-building-principles

過去大家只專注在 IOS, Android, PC,... 等等傳統平台。
但現在 KKBOX 開始著眼於其他 IoT 設備。

> KKBOX 是軟體工作，以軟體公司思維思考

Internal API -> Restful service

## OpenAPI
* 全世界都可以找到
* 想要更多功能會跟 KKBOX 說
> 接不到就會自己放棄！

(PS 過去跟其他廠商合作時，常會被很多廠商的需求搞垮，因此開始從 Internal API 走向 Open API 之路)

## Why developers like SDK
* 開發者很懶
* 處理複雜認證流程
* 例如 取得 access token 需要 hash/MD5
* IDE Autocomplete

## 那麼該用什麼語言當作開發 SDK 的語言呢？
* JavaScript 在各類型 Client 都有 solution
// 目前 JavaScript / Python 在 github 上並駕齊驅XD

## SDK Principle
### 化零為整
* 把 Endpoint 相關的封裝成一個 Class
* 用屬性 set ID

### 化繁為簡
* 將重複瑣碎的動作簡化
* Access Token 都需要塞 header
* territory 語系通常在 App 啟動後就不會改變
* 每次都要帶入請求，但可透過 class 屬性設定
* 為何 API 不能做到? 因 API 是 stateless

### 化無為有
* SDK 可實現 API 沒有的功能
* 不能牴觸 API 原來的設計理念
* 例如原本 API 有分頁，就不應該做一個 `fetchAll` 拿到幾十萬筆資料
* Open API 不能取得音檔，但可以透過 Web Widgets 播歌

## Testing by Mocha
### 監控分兩面
1. inside
2. outside
* 例如網路出問題、回應速度太慢
* 確保服務品質

## Documentation by ESDoc

寫文件有兩個訣竅：

1. 要提供 url 指向對應的 class
2. 要提供詳細的 example 講解怎麼開始、怎麼使用、輸出為何

## 版號規則
* New Product ==> 1.0.0
* Patch release ==> 1.0.1 改第三碼
* Minor release ==> 1.1.0 改第二碼
* Major release ==> 2.0.0 改第一碼

## Marketing

透過 showcase 行銷