# 如何利用 OpenAPI 及 WebHooks 讓老舊的網路服務也可程式化 - 王慕羣 (Kewang)

{%hackmd j86FNbMoRoeN4Xn0pg5ofw %}

> 請從這裡開始

{%slideshare kewang/openapi-webhooks %}

Open data:
- 資料必須完整釋出
- 只能依照再製成本徵收適當的費用
- 最好是能提供網路下載
- 提供的資料格式必須是適用和可修改的
- 資料是初時必須採用允許資料的重新使用和散播的授權聲明
- 允許與其他資料混和使用
- 任何人都可用
- 不限制使用範圍

可互通性 interoperability

Open Data -> OpenAPI

唐鳳的定義

自動發現
metadata包含可讀取內容
寫程式就搞定政府網站

機器可寫入
公務體系除非一開始就約定好相同結構的結構資料，不然很難做到跨機關界皆
公文、報稅不一定要用原本設計
新載具出現的時候可以連接到機器可寫的入口

公文系統： MSON, git, GPG key
- [MSON](https://github.com/apiaryio/mson) DSL：對公文格式標準化
https://github.com/apiaryio/attributes-kit
- git, GPG key：保證不被竄改

報稅系統：
- Chrome Extension 強化報稅體驗
- OpenAPI 讓各家廠商深度整合自家系統
- 安全性要做處理

## Open API 實作

把API作為Library使用
tw.kewang.cwb
[https://kewang.github.io/cwb-lib-java/](https://kewang.github.io/cwb-lib-java/)

- 申請API Key
- 了解data schema
- 回傳原始格式及易用格式
- 使用SemVer定義版號
- 使用GitHub管理
- 撰寫JavaDoc
- 上傳到Maven Central

缺點：
- 沒有API可用
- 需要為每個與元寫Library
- vendor變更data schema時無法立刻得知

https://github.com/kewang/cwb-lib-java
http://opendata.cwb.gov.tw/usages

agent -> OpenData
-> Server -> OpenAPI

- agent定時取得OpenData並存在Server上
- server提供openAPI給使用者用
- 使用APIKEY管理
- 了解data schema
- 規劃API版本
- 撰寫API文件

http://www.books.com.tw/products/CN11128893

優點
- APIKEY
- 記錄使用量、來源
- 限制使用量、來源
- 不怕vendor變更data schema

缺點：
易被當成DDOS
無法完全即時更新

## Internal API

Internet API -> Adapter -> Open API
使用APIKEY
使用Adapter將OpenAPI及Internal API互轉
使用middle ware將APIkey轉回....
撰寫API文件

優點
Adapter：
Internal API及OpenAPI的request與response欄位不同，用Adapter做轉換

> apikey取代帳戶密碼，保障敏感資料不外洩
> 意思大概就是不要用 basic 驗證？
> (答：所指的是 HTTP Basic Auth 嗎？)

API Blueprint：
MSON、Markdown
Swagger

## Webhook

http://webhooks.kewang.tw/

client <-> server -> vendor

實作方式：POST action
- 將server的request與response用POST給vendor
- 不可以讓webhook拖到api行為
- 避免影響API運作
- 在middleware新開thread或丟到MQ去執行

使用SSL
- vendor不使用SSL -> 明碼出去，不建議
- vendor使用自簽憑證 -> 容易有error
- vendor使用合法憑證 -> OK

request token
- 讓vendor驗證資料是從server來的
- 把雙方約定好的token放在header中再傳送
- vendor比較header是否與約定好的token相同
- 相同：資料未被竄改
- 不相同：資料被竄改

實作方式：HMAC-SHA256
- 把資料用server與vendor約好的token計算出HMAC-SHA256(H1)
- server將資料與HMAC-SHA256直接傳送到vendor
- vendor使用token將接收到的資料計算出HMAC-SHA256(H2)
- 比較H1與H2是否相同
- 相同：資料未被竄改
- 不相同：資料被竄改

相同的data schema
- openapi與webhook都是串接服務，應該data schema要相同

## Summary
- OpenAPI
- 清楚的文件
- 不要用帳密，用token
- 用middleware

- Webhook
- 清楚的文件
- 獨立thread運作
- 驗證來源是否合法

Qmi
[http://www.qmi-promo.emome.net/qmi_c.html](http://www.qmi-promo.emome.net/qmi_c.html)

###### tags: `MW18`