web API設計閱讀筆記(二)

章節六建立API模型

可以用表格去列出API的項目，記載的欄位應包含API基礎的資訊，如名稱、說明、存取範圍、輸入參數、輸出結果格式和涉及的資源模組..等，這些基本資訊就是API profile，並不涉及API的風格和實作技術。
設計先行於實作，避免在錯誤的基礎上蓋房!且這裡的設計是從應用的角度出發，API設計和資料庫schema設計的考量並不相同，API設計是針對資源(data transfer object,DTO)做操作，並非直接對資料模組(model)去使用。

書中舉例，API profile列表後，可以再透過時序圖來檢視API的操作行為，藉以設想當中資源的變動情況。更進一步的評估，是對商業價值、開發難度和替代方案設想，例如公司可能沒有能力去做一個Payment API，替代方式是去尋找市場上已經有商業方案的廠商所提供的產品。

HTTP是最普遍被使用的通訊協定，也因此HTTP架構的特性，會對影響到API的設計。
1.主從式架構：服務端與客戶端相互獨立，兩者間是使用請求/回覆的機制進行訊息互動。
2.無狀態：服務端不會紀錄客戶端的狀態，所以每次客戶端請求要附上驗證資訊。
3.分層式架構：服務端對客戶端像是個黑盒子，服務端是由不同的模組堆疊出來，一個請求可能經過了快取、反向代理、認證等才到對應的模組。
REST風格是要去約束和約定出一致的設計介面的思維，JSON和CRUD只是REST風格當中兩個常用的設計元素。
使用HTTP協議下所採用的REST風格，API設計會有下列的特性：
1.主從式架構(前後端分離)
2.以資源為中心(資源可以展現成JSON、CSV、XML等各種表現格式)
3.互動以訊息為基礎(Http的表頭、body、URL和參數等等都帶有訊息)
4.支援分層式架構(可以有許多中介層存在，比如logging、OAuth、cache..等)
使用HTTP操作方法和URL(資源路徑)，並定義HTTP的回應代碼(200系列、400系列、500系列)加入到API profile當中。

CRUD可以視為一種REST實作的設計形式，書中建議對於資源的操作，應避免讓客戶端發起多次請求來完成某項任務，這會影響到更複雜的回退(還原)機制，也因此再次強調不要用資源不等於資料模型的必要性。

實際專案上，遇見過這種糟糕的情況，後端把API設計直接對應資料模型的操作，讓客戶端必須去多次請求/操作資料後來完成某項任務，非常不建議如此實作。

書中舉例，訂位服務如果需求是可以一次預約多席，那第二種POST的實作方式是更推薦的。

PUT /seats/{seatId} to reserve seat

POST /reservation ##推薦
{
    "seatIds":["id1","id2"...]
}

書中介紹REST風格以外常見的這兩種API形式。著名的GraphQL是Query-Based API的風格。

webhook建立的訂閱和通知模式
比如使用lineBot的串接中，有人傳送訊息到官方頻道，在line後台可以設定一個回呼的POST /callback/linebot，服務端基於這樣的回呼可以來再發送訊息
websocket建立雙向通知
讓客戶端和服務端可以透過websocket相互發出請求/回應。