WEBAPI設計原則

#API

WebAPI設計原則

ＡＰＩ擁有『永久性』的特性，好壞的設計都會伴隨著，不管未來改版與否，舊版本依然很難拿掉，請謹慎設計。

API設計優先

設計ａｐｉ千萬不要孤軍奮戰

千萬記得跟技術/非技術的人參與討論，懂技術的規劃一定不平衡不健全

探索：確認ＡＰＩ的需求以及確認是否現有的ＡＰＩ已經能滿足用戶需求
設計：因應客戶需求規劃ＡＰＩ設計，或改善現有設計
製作原型：製作原型API(Prototype API) 或擬真API(Mock API) 供大家使用，加速取得反饋並加以改進
交付：根據圓形與設計、測試、文件三項工作同時開發．不追求一次性完成，而是迭代優化循環，才可以逐步完成交付進度。
上線：讓內外部用戶使用ＡＰＩ進行串接，良好的客戶支援此階段中最重要。

Domain Model 轉為 Web API 設計 (ADDR)

ＡＰＩ設計會經歷四個階段，使用七個步驟來進行

目的

最終交付的產品能解決客戶問題，並且ＡＰＩ設計符合客戶認知
終結混亂的設計流程，減少無謂的設計變化與重構
透過系統性的方法提高交付的效率
透ㄍㄨㄛˋ流程內的機制，讓技術/非技術方都有表達意見的機會，最終形成彼此共識
流程中的每個階段產出的文件、紀錄，都是有系統、可追溯、可傳承，而不是像白板上臨時起意的塗鴉讓人摸不著頭緒

四個階段

Align(對齊)：確保商業、產品、技術團隊對產品範圍與目的都有共同且一致的認知
Define(定義)：將商業與客戶需求轉成對應的數位能力，成為ＡＰＩ實作的基礎
Design(設計)：依照特定的步驟制定ＡＰＩ社既文件，並選定適合的ＡＰＩ風格
Refine(優化)：根據用戶回饋優化ＡＰＩ設計、文件、原型、測試

七個步驟

鑑別數位能力：釐清用呼需求，定義出能解決需求的數位能力
產生活動與步驟：從用戶的動機、需求、與情境中找出具體的步驟並將步驟所對應的數位能力納入ＡＰＩ設計中
界定ＡＰＩ邊界：將ＡＰＩ依照相關性分們別類，以及確認是否可以用計有ＡＰＩ滿足客戶需求，縮短交付時間
建立ＡＰＩ模型：建立ＡＰＩ模型，產出ＡＰＩ Profile作為後續高階設計的基礎
高階設計：選擇適合的ＡＰＩ實現風格，製作高階設計文件
優化設計：蒐集ＡＰＩ用戶反饋改進產品
撰寫ＡＰＩ文件：包括ＡＰＩ歸格文件與入門指南，方便用戶進行串接

第三章

鑑別數位能力

企業組織提供自動化機制的能力模型

商業能力往往用ＫＰＩ或ＯＫＲ等指標來追蹤，但數位能力重視的是成果的產出，以期為了獲得商業能力所必要的行動。
商業能力表示的是組織的「What」，而數位能力表示的是組織的「How」。

JTBD (Job to be done)

原則二：api設計是目標導向

藉由目標導向ＡＰＩ才是真正對用戶有意義。

Job Story

挑戰一：太多細節

故事主要在於抽象的行動，細節可以用「附加細節區」，跟寫程式的抽象、介面的方法一樣，找出相同的動作而不是實作細節。

挑戰二：太偏向功能面

一樣要抽象，不要專注在功能面

第四章

產生活動與步驟

從第三章的上圖第4點，「找到一兩本想買的書、下單、買到他然後等收貨」是一個比較抽象的說法，但要如何把他拆解出來變成「產生活動」？

對於不熟悉的領域，我們需要尋求外部的協助，這時候就需要利用事件風暴找出共識

利用事件風暴求出共識

這是一個團體活動，將一個未知的各個層面的商業流程、需求、事件等已具象化的方式呈現，透過一系列活動凝聚成員共識。主要增進的事我們對於特定領域的知識與共識，讓團隊具備通同的知識後，再帶回到各自的ＡＰＩ之中。

事件風暴如何進行

這邊描述的應該有的幾個步驟、該如何進行、誰要參加、最終成果，但這個後續再來玩，太有趣了。

成立一次事件風暴

界定ＡＰＩ邊界

ＡＰＩ的反例

超級多合一ＡＰＩ反模式

超肥的ＡＰＩ讓開發者感到疑惑與挫折，太過於細碎也會有一樣的狀況。這就太過於極端不會犯這種錯誤．

超載ＡＰＩ反模式

一隻超完美的Accounts API 提供完整的帳戶資訊，或一隻完美的Customer API提供用戶完整資訊，理想很豐滿、現實很骨感，這種完美個ＡＰＩ都不會有好下場。

重要觀念

書其實就是產品「Product」，應該區分用於分類使用、商品呈現使用、出貨用、訂單用，都各有自己的重要使命。這樣的ＡＰＩ區分出來以後，可預見分類或是產品、購物車用的ＡＰＩ的Request需求大於訂單跟出貨，又可以把它拆解出來。

用事件風暴界定邊界

跟之前學習到的DDD 一樣把這些行為模式列舉出來之後，就會找到很多相關詞，把這些相關詞列出來之後，就可以找到他的邊界

這邊提供兩個方法來界定他的邊界

使用共同詞彙

使用`聚合`作為邊界

要注意使用聚合作爲依據可能會因為範圍的顆粒度不同，導致每個ＡＰＩ的精細度不同，所以要注意

第六章建立API模型

好的API設計來自於 API模型，API模型協助制訂一個API的範圍與用途、搞懂與驗證Client端與外部開發者的需求，跟畫面的Prototype不一樣(滿足客戶)，API模型滿足開發者、Client的操作感受盡管兩者的需求是共同的但還是會有些差異，透過API建模的過程，能找出差異並建立解決方案，避免在錯誤的基礎上蓋房子。

建模API的素材來自於前面幾張，活動、步驟、工作故事，彙整過後就是API Profile。API Profile 包含一切特性，有名稱、範圍、事件，有API模型的存在有機會告早在模型中發現問題並加以修正，相較於重構的成本真的太划算了。

API Profile 結構

一份典型的 API Profile包含有以下項目

API的名稱與說明
API的存取範圍(Internal、Public、partner..等)
API的操作及輸出入的詳細參數與格式
API操作的可存取人員名單，品開放白名單內人員調用，避免安全隱患
API操作具有的事件
(選填)額外的標準或規範要求，例如 SLA

建議是可以共同協作的線上文件、Wiki...等等

為何不使用OpenAPI(SWagger)來當作API模型文件?

他是屬於讀取程式碼的REST或gRPC的規格書，他用途是API技術參考文件與範例程式，但是他會是後續建立API profile的好的素材。

第一步：建立 API profile概要

定義基本資料，包括名稱、說明、範圍(internal、public、partner)等等，命名方式建議使用 lowerCamelCase，這對後續的時序圖會有幫助。

第二步：找出相關資源

找出跟PAI操作有關的事物，API的每個操作都會調動到的事物，聽起來很抽象，但其實之前我們已經對齊(Align)很定義(Define)階段就已經整理過了。

其中的Books、Cart，這些之前就已經定義清楚了。

注意

標示資源為何不直接拿DB的欄位作為對應?

資料庫設計注重結構與效能設計(正規化/反正規化)，API層注重的是用戶導向並不是讀寫的效能，因此不建議拿DB Table作為對應資源
思考應該由高至低，如果從Table 開始會太多細節在裡面。

第三部：定義資源階層

資源間的層級關係(taxonomy)制定出來，所謂的taxonomy是一個分類與組織事務的術語，用來表示階層資源間彼此的層次與關聯性。

資源關係有三種表達方式：

Independent(獨立的)：資料獨立存在，與其他資源不互相依賴
Dependent(依賴的)：一個資源必須依賴其他資源才能存在，父子概念(子無法單獨存在)。(依賴跟參考是不同的概念：如果兩個獨立的(Independent)互相參照並不表示他有依賴性，他們仍然是各自獨立)(如下圖範例)
Associative(關聯的)：兩個獨立的資源，而兩者間又需要建立起關係才能完整表達事務的全貌，這種狀況或加入一個中介資源來捕捉他們的關係，這種結構下那兩個互相獨立的資源的關係稱為associative。

下圖 Book資源跟 Book Author 資源 是各自獨立的，但又可以互相參考讓事情全貌更完整。

上圖中有一個書籍的數量該放哪呢?，就如下圖，當一本書被放進購物車那書的數量、金額應該怎麼放呢? 引入另一個資源CartItem來存放這些購物車的閔項細節。

因為引入CartItem，為了讓名稱一致，原本操作addBookToCart()改成 AddItemToCart()、removeBookFromCart()改為removeItemCart()

加入事件操作

確認階層過後補完每個API操作具有的事件，API操作發送出的事件可以為API客戶端所使用，例如資料分析、客戶端收到事件後也能在對API發起別的請求

此處的事件可以參考事件風暴中的那些事件，做事件風暴的時候有定義有哪些事件，如果你未曾使用事件風暴，也可以用之前建模時所設定的那些事件。

事件的命名請使用過去式，除此之外如果組織內既有的命名原則應該遵循

補充細節

我們將填入每一個操作的參數細節，包括他的

輸入參數
輸出格式，但並不要求填滿完整細節，這邊填寫重點即可，也可以預留空格。
同步(synchronous)或非同步(asynchronous)的資訊，這會影響後續設計階段的作業，同步API最基本一筆請求/一筆回復這樣來回拋接的作業模式，非同步 API會將請求放置背景處理。
安全性：不會對資源做出狀態變更的動作，對於讀取資源(GET)類的方法應該都要是safe的
不安全(unsafe)：會改變資源狀態且重複操作也不保證會得到相同結果，多半出現在(PUT和PATCH)
冪等操作：具有冪等性的話，可以讓客戶不用擔心取代資源或是刪除資源(PUT與DELETE)

Source:200-Areas/230-知識擴展/讀書筆記/WEBAPI設計原則/WEBAPI設計原則

ShoppingAPI.profile完整範例

Shopping API

Supports the book browsing experience and cart management
Scope: Public

Operation Name	Description	Participants	Resource(s)	Emitted Events	Operation Details	Traits
listBooks()	List books by category or release date	Customer, Call Center	Book, Book Author	Books.Listed	Request Parameters: categoryId, releaseDate Returns: Books[]	safe / synchronous
searchBooks()	Search for books by author, title	Customer, Call Center	Book	Books.Searched	Request Parameters: searchQuery Returns: Books[]	safe / synchronous
addItemToCart()	Add a book to the customer's cart	Customer, Call Center	Cart Item, Cart	Cart.ItemAdded	Request Parameters: cartId, bookId, quantity Returns: Cart	unsafe / synchronous
removeItemFromCart()	Remove a book from the customer's cart	Customer, Call Center	Cart Item, Cart	Cart.ItemRemoved	Request Parameters: cartItemId Returns: Cart	idempotent / synchronous
clearCart()	Remove all books from the customer's cart	Customer, Call Center	Cart	Cart.Cleared	Request Parameters: cartId Returns: Cart	safe / synchronous
viewCart()	View the current cart and total	Customer, Call Center	Cart	Cart.Viewed	Request Parameters: cartId Returns: Cart	safe / synchronous

用時序圖驗證API模型

確保API作業如預期，我們使用時序圖來驗證並且拿此圖來跟大家討論API作業的意見。

確認API profile的特性是否跟工作故事的特性一致、沒有做歪。不是畫圖就結束，我們要邊畫邊模擬真實的互動情境，設想每個操作，資源是不是符合預期，中間是否有缺漏，如果有請回到建模步驟再次補完。

驗證完畢後將API模型分享給大家，包括技術和非技術、外部專家、早期用戶等，徵求反饋，進入設計階段前，務必要確保目前的成果是大家一致認可的。

sequenceDiagram
    participant Customer
    participant Shopping API
    participant Order Creation API
    participant Payment Processing API

    Customer->>Shopping API: listBooks()
    Shopping API-->>Customer: Books[]
    Customer->>Shopping API: addBookToCart(bookId)
    Shopping API-->>Customer: Cart
    Customer->>Shopping API: removeBookFromCart(bookId)

    Customer->>Shopping API: searchBooks(searchQuery)
    Shopping API-->>Customer: Books[]
    Customer->>Shopping API: addBookToCart(bookId)
    Shopping API-->>Customer: Cart

    Customer->>Shopping API: viewCart()
    Shopping API-->>Customer: Cart
    Customer->>Order Creation API: createOrderFromCart(cartId)
    Order Creation API-->>Customer: Order

    Customer->>Payment Processing API: payForOrder(orderId)
    Payment Processing API-->>Customer: PaymentDetails

評估API優先順序與重用性

評估API提供的商業與市場價值，試問自己幾個問題

API在市場上有競爭優勢嗎?
API能取代過去的人工作業嗎? 能省下過往的人工成本嗎?
API能開闊新的收入管道嗎?或是增加原有的收入管道?
API能帶來哪方面的商業效益呢?是BI(商業智慧)?市場洞察?或是決策因子?
API帶來的自動化效益可以讓企業組織的核心業務做到更多更好嗎?

以上答案皆非，那不用做了，如果有正面的肯定答案就表示可以做了。

再來評估每隻API的難度，API的難度可以用在事件風暴所產生的步驟來估計，越多步驟、複雜、時間，難度就越高，反之亦然，可區分低、中、高。
看看現有的資源是否有可以拿來使用修改，不需要自己重新造輪子

總結

資源的階層(taxonomy)：表示資源間的關係是否互相依賴
API profile：API高階設計文件，不涉及特定設計風個或實作技術
時序圖：驗證API模型是否與工作故事相一致
評估優先度：確保API的存在價值

了解整體核心價值後，可以把非核心業務由外部API處理(或初階工程師)，或沿用現有的，找到平衡點。

第七章 REST API

REST 被設計適用於粗顆粒度的訊息交換，儘管這是Web最普遍的形式，但對於其他形式，REST就不是最佳解。
REST是一來一往的過程，並不能像 RPC可以達到非同步也沒有結構性約束，頁面上的操作往往是比較粗的呈現(適用REST)，想要更細的操作(RPC這類就不錯)
沒有特別需要細粒度的需求，一班都會選擇REST作為主要API風格

提示

REST從來就不是CRUD + JSON，是一系列的架構性約束與約定，這些約束與約定制定了一個系統的模組間該如何有效的工作與互動

REST的架構性約束給系統更好的靈活性(flexibility)與進化性(evolvability)

主從式架構：服務端與客戶端互相獨立，兩者之間用請求/回覆的機制進行訊息互動。
無狀態：服務端不會記憶客戶端的狀態，所以每次客戶端發送請求時都要附上用戶的驗證資訊。注意：服務端自身的狀態式會儲存的。
分層式系統：對客戶端來說服務端就像是黑盒子，但服務端的角度來看黑盒子的內部式許多的子模組堆疊起來，每一層負責的任務不同，例如：快取、反向代理、認證...等等。
Code on demand(選配)：客戶端的程式碼可以來自服務端，可能是腳本也可能是二進位程式，瀏覽器跑Web APP就是Client、API可能是SDK。客戶端只負責執行環境，商業邏輯由服務端掌控，改版時也不西澳客戶端搭配升級。
一致的介面：REST得以上架構性約束，讓API對外形成一致的介面。
Hypermedia特性：除了原本的資料，還可以挾帶其他資訊(這就稱為：Hypermedia)，讓客戶端了解更多可能性、額外操作、狀態等等，這樣可以避免客戶端帶來頻繁的操作影響效能，典型案例就是分頁的元素。
從這邊來看，下一頁、上一頁這類的已經把資料產生好並且直接給連結，這樣可以做好快取讓使用者來讀取這頁的快取資料，而不是直接呼叫API來動態產生資料消耗資料庫資源
HATEOAS (hypermedia as the engine of application state) ：回覆資料提供額外的資訊，甚至可以根據狀態提供Client可以採取的動作(上一頁、下一頁，編輯/佔存、同意/拒絕)