API需求與設計下的模型
在前一篇文章中，我們探討了程式設計下的模型（Model）與資源導向的 API 設計，今天我們將深入討論在 API 需求與設計下的模型。這部分內容對於確保 API 能夠滿足業務需求、具有良好的可維護性和擴展性至關重要。
什麼是 API 模型（需求下的）？
API 模型是 API 設計的核心，它描述了如何將系統中的業務邏輯和資料結構映射成 API 的資源和操作。API 模型不僅僅是數據的結構設計，更是使用者與系統交互的基石。通過 API 模型，我們定義了哪些資源可以被訪問、可以執行哪些操作，以及這些操作將返回什麼樣的結果。
換句話說，API 模型是 API 的「骨架」，它支持著 API 的所有功能，並確保這些功能能夠被使用者正確且一致地使用。
什麼是 API Profile？
在 API 設計中，API Profile 扮演著「設計圖」的角色，它幫助我們在設計階段確保 API 的整體結構合理且符合業務需求。API Profile 涵蓋了資源、操作、資源之間的關聯、以及使用這些資源時的約束條件。
API Profile 是 API 設計的基礎，它幫助團隊在設計早期階段建立共識，並提供一個參考框架來進行後續的詳細設計和實現。
API 建模流程
建立 API 模型是一個循序漸進的過程，需要從高層次的需求開始，逐步細化到具體的技術實現。以下是 API 建模的基本步驟，每一步都將幫助我們確保 API 的設計能夠滿足需求並具備良好的可擴展性。
1. 建立摘要
首先，我們需要明確 API 的主要目標和用途。這一步驟就像是在設計一個新產品之前，先確定它的市場定位和目標客戶群體。我們要清楚 API 的核心功能、目標使用者，以及預期的業務流程。
在這個案例中，我們將開發一個圖書管理與會員管理系統，並且處理會員借書的相關業務。這個系統的核心功能包括圖書的查詢、增加、更新、刪除，以及會員的管理和借書記錄的處理。
操作名稱說明人員資源事件操作細節
SearchBook
搜尋書籍
會員、管理者
AddBook
新增書籍
會員、管理者
UpdateBook
更新書籍
會員、管理者
DeleteBook
刪除書籍
會員、管理者
SearchMember
查詢會員
會員、管理者
AddMember
新增會員
會員、管理者
UpdateMember
更新會員
會員、管理者
MemberRentBook
會員租借書籍
會員、管理者
2. 找出相同資源
在 API 中，資源通常代表系統中的實體，比如圖書管理系統中的「圖書」、「會員」、「借閱記錄」等。我們需要明確這些資源的定義，並對它們進行詳細描述。
這一步的目的是識別出系統中哪些資源是 API 需要處理的，並確保我們不會遺漏重要的資源。例如：
- 圖書（Book）：描述圖書的基本信息，如標題、作者、ISBN 等。
- 會員（Member）：描述會員的基本信息，如姓名、會員編號、聯繫方式等。
- 借閱記錄（Loan）：描述圖書借閱的記錄信息，如借閱時間、歸還期限、借閱者信息等。
這些資源將構成 API 的基礎，我們需要對它們進行詳細設計。如下表範例所示，先找出操作名稱中的名詞來定義出相同的資源。
操作名稱說明人員資源事件操作細節
SearchBook
搜尋書籍
會員、管理者
AddBook
新增書籍
會員、管理者
UpdateBook
更新書籍
會員、管理者
DeleteBook
刪除書籍
會員、管理者
SearchMember
查詢會員
會員、管理者
AddMember
新增會員
會員、管理者
UpdateMember
更新會員
會員、管理者
MemberRentBook
會員租借書籍
會員、管理者
3. 定義資源階層
資源之間的關係和層次結構是設計 API URI 結構的基礎。定義資源的階層結構有助於使 API 更加直觀和易於理解，這樣的階層結構清楚地展示了資源之間的關係，使得 API 使用者可以輕鬆地理解和使用 API。
在表格中，我們可以進一步將資源的階層結構明確列出，並展示出每個資源之間的關聯性。例如：
操作名稱說明人員資源事件操作細節
SearchBook
搜尋書籍
會員、管理者
Book
AddBook
新增書籍
會員、管理者
Book
UpdateBook
更新書籍
會員、管理者
Book
DeleteBook
刪除書籍
會員、管理者
Book
SearchMember
查詢會員
會員、管理者
Member
AddMember
新增會員
會員、管理者
Member
UpdateMember
更新會員
會員、管理者
Member
MemberRentBook
會員租借書籍
會員、管理者
Book、Member
4. 加入操作事件
在定義完資源後，我們需要確定使用者可以對這些資源進行哪些操作。這些操作通常包括 CRUD 操作（創建、讀取、更新、刪除），以及其他業務邏輯相關的操作。
在這一步中，我們要把每一個操作事件的細節和處理流程補充完整，確保操作的完整性和一致性。比如，在這個系統中，我們需要定義圖書資源的CRUD操作、會員資源的管理操作以及借書的業務邏輯。
這些操作應該包括詳細的請求格式、參數要求和返回格式，以確保 API 使用者能夠正確地執行操作。
操作名稱說明人員資源事件操作細節
SearchBook
搜尋書籍
會員、管理者
Book
Books.Get…
AddBook
新增書籍
會員、管理者
Book
Books.Add
UpdateBook
更新書籍
會員、管理者
Book
Books.Update
DeleteBook
刪除書籍
會員、管理者
Book
Books.Delete
SearchMember
查詢會員
會員、管理者
Member
Member.Get
AddMember
新增會員
會員、管理者
Member
Member.Add
UpdateMember
更新會員
會員、管理者
Member
Member.Update
MemberRentBook
會員租借書籍
會員、管理者
Book、Member
Member.RentBook.Add.Book
5. 補充操作流程
操作流程的設計對於 API 的一致性和安全性至關重要。在這一步，我們需要對每個操作的細節進行補充，因為我們是開發Web API，所以可以使用HTTP方法來輔助操作細節的建立。同時，我們還需要考慮 API 的安全特性，確保敏感操作受到適當的保護。
先前有講到HTTP方法，這邊在複習一下：
• GET：用於讀取資源，應當是安全且無副作用的。
• POST：用於創建新資源，應當具備非冪等性，即多次重複執行可能導致不同結果。
• PUT：用於更新現有資源，通常是冪等的，即多次執行會得到相同結果。
• DELETE：用於刪除資源，應當具備冪等性。
• PATCH：用於部分更新資源，和 PUT 類似但應用於局部變更。
再來是何謂安全特性：
- Safe：（安全的），不會對資源做出狀態改變的方法。
- Idempotent：（冪等的），一個操作會改變資源的狀態，但重複操作不會重複改變該資源得狀態。
- UnSafe：（不安全的），一個操作會改變資源的狀態，重複操作會重複的改變資源的狀態。
最後節合在一起來看
HTTP 方法簡介與安全特性：
HTTP方法說明安全特性安全特性說明
GET
回覆請求的資料
Safe
不會改變現有資源狀態
POST
創建資源或其他應用
UnSafe
重複一樣的新增，可能會產生多比相同的資源
PUT
取代現有的資源
Idempotent
重複一樣的取代不會產生多個重複的資源
PATCH
更新資源
UnSafe
重複一樣的更新可能會讓資源有重複的屬性
DELETE
刪除資源
Idempotent
重複一樣的刪除不會改變資源已被刪除的狀態
以上這些HTTP 方法與安全特性，在Web API的篇章已經提到過一次了，現在又出現就能說明他對於Web API 的正確設計上舉足輕重，在正確的設計下，要想到他的操作細節應該是屬於何種類型，會對資料造成何種影響，這樣能夠更好的完成API模型設計。
操作名稱說明人員資源事件操作細節
SearchBook
搜尋書籍
會員、管理者
Book
Books.Search…
請求參數：BookSearch
回傳值：Book[]
safe / sync
AddBook
新增書籍
會員、管理者
Book
Books.Add
請求參數：Book
回傳值：bool
Unsafe / sync
UpdateBook
更新書籍
會員、管理者
Book
Books.Update
請求參數：Book
回傳值：Book
Idempotent / sync
DeleteBook
刪除書籍
會員、管理者
Book
Books.Delete
請求參數：Book.Id
回傳值：bool
Idempotent / sync
SearchMember
查詢會員
會員、管理者
Member
Member.Search
請求參數：MemberSearch
回傳值：Member
safe / sync
AddMember
新增會員
會員、管理者
Member
Member.Add
請求參數：Member
回傳值：bool
Unsafe / sync
UpdateMember
更新會員
會員、管理者
Member
Member.Update
請求參數：Member
回傳值：Member
Idempotent / sync
MemberRentBook
會員租借書籍
會員、管理者
Book、Member
Member.RentBook.Add
請求參數：Member,Book[]
回傳值：Book[]
Unsafe / sync
使用時序圖來驗證 API 流程
在完成上述步驟後，我們可以使用時序圖來驗證 API 的流程。時序圖是一種視覺化工具，可以幫助我們確認 API 操作流程是否合理，以及資源之間的交互是否清晰。它展示了在一個操作過程中，系統中的各個實體如何互動，並清晰地展示了操作的順序和邏輯。
例如，對於「借閱圖書」這個操作，我們可以設計一個時序圖，展示會員請求借閱圖書、系統檢查圖書可用性、創建借閱記錄，並通知會員的整個流程。這樣的時序圖能夠有效地驗證我們設計的 API 是否符合預期，並且可以幫助我們識別和解決潛在的設計問題。
總結
設計 API 模型是一個需要深思熟慮且逐步完善的過程。從建立摘要、找出資源、定義資源階層，到加入操作事件和補充操作流程，每一步都至關重要。最後，通過使用時序圖來驗證 API 流程，我們可以確保 API 的設計不僅符合業務需求，還能在實際應用中高效運行。
這些步驟不僅能幫助我們建立一個強大而靈活的 API 模型，還能確保 API 在未來的變化中保持穩定和可靠。通過良好的 API 設計，我們可以為開發者提供一個易於使用、功能強大的接口，為最終用戶帶來更好的體驗。
這就是 API 模型設計的核心理念：將複雜的業務邏輯轉化為簡單、清晰的 API，讓使用者可以輕鬆操作並獲得所需的結果。
