本書從“由外而內”的角度引入 API 設計，重視反映客戶和產品團隊的聲音，將需求映射到特定的、組織良好的 API，為編寫這些 API 選擇正確的風格，并從零開始實現了一個真實的例子，旨在為設計新 API 或擴展現有 API 的人提供指導，幫助他們了解如何通過正確的設計過程來交付優秀的 API，如何與設計團隊、客戶和其他涉眾就具體的成果達成一致，如何確定正確的 API 并將操作整合成統一的 API 配置文件，以及如何使 API 程序實現可伸縮的設計和管理過程。本書適合所有參與規劃或構建 API 的讀者閱讀，包括架構師、開發人員、團隊領導者、單團隊和多團隊環境中的項目管理人員，以及相關技術人員或業務專業人員。
1. Web API設計類圖書，作者超過25年API設計經驗的結晶，內容詳實，易于理解。
2. 包含從0到1的實踐案例，又有源于實踐又高于實踐的“內功心法”——規范和原則，引導你掌握創新思維，站在科技與商業趨勢的前沿。
3. 內容涵蓋了API設計的各個方面，適合所有參與規劃或構建API的讀者，幫助讀者輕松解決API設計難題。
4. 從外部視角引入API設計，強調反映客戶和產品團隊的需求和聲音。有助于確保設計的API能夠滿足實際需求，提供出色的客戶體驗。
[美]詹姆斯·希金博特姆（James Higginbotham）是一名軟件開發人員和架構師，在開發、部署應用程序和 API 設計方面擁有超過 25 年的經驗。他擅長與銀行、商業保險、酒店、旅游、航空等行業的團隊和企業合作，能幫助團隊將業務、產品和技術策略統一到更易組合和模塊化的企業平臺，指導企業完成數字化轉型之旅。
詹姆斯曾多次舉辦研討會，熱衷向跨職能團隊推薦他提出的 ADDR 流程——通過基于產品的思維來確保業務和技術之間的一致性，以提供出色的客戶體驗。
第 一部分 Web API設計簡介
第 1章 API設計原則 3
1.1 Web API設計要素 4
1.1.1 業務功能 4
1.1.2 產品思維 4
1.1.3 開發者體驗 5
1.2 API設計即溝通 6
1.3 審查軟件設計的原則 7
1.3.1 模塊化 7
1.3.2 封裝 8
1.3.3 高內聚和松耦合 8
1.4 基于資源的API設計 9
1.5 資源不是對象或領域模型 11
1.6 基于資源的API交換消息 11
1.7 Web API設計原則 13
1.8 小結 13
第 2章 協作式API設計 15
2.1 為什么需要API設計流程？ 15
2.2 API設計流程反模式 17
2.2.1 泄露抽象反模式 17
2.2.2 下一個版本設計修復反模式 18
2.2.3 英雄設計工作反模式 18
2.2.4 未使用的API反模式 19
2.3 API設計優先的方法 19
2.4 API設計優先并保持敏捷 20
2.4.1 重新審視敏捷宣言 21
2.4.2 API設計優先的敏捷性 21
2.5 對齊-定義-設計-優化流程 22
2.6 DDD在API設計中的作用 24
2.7 API設計涉及每一個人 25
2.8 有效應用ADDR流程 26
2.9 小結 26
第二部分 對齊API的結果
第3章 明確數字功能 29
3.1 確保利益相關者思路對齊 30
3.2 什么是數字功能？ 31
3.3 專注于要完成的工作 32
3.4 什么是任務用例？ 33
3.5 任務用例的組成部分 33
3.6 為API編寫任務用例 34
3.6.1 方法1：當問題已知時 35
3.6.2 方法2：當期望的結果已知時 35
3.6.3 方法3：當數字功能已確定時 35
3.7 克服任務用例的挑戰 36
3.7.1 挑戰1：任務用例過于詳細 36
3.7.2 挑戰2：任務用例以功能為中心 36
3.7.3 挑戰3：任務用例需要額外的用戶上下文 37
3.8 收集任務用例的技巧 37
3.9 現實世界中的API設計項目 38
3.10 任務用例示例 39
3.11 小結 39
第4章 收集操作和步驟 41
4.1 將任務用例擴展為操作及其對應的步驟 42
4.1.1 確定每個任務用例的操作 43
4.1.2 將每個操作分解為若干步驟 43
4.1.3 如果需求不明確，怎么辦？ 44
4.2 通過事件風暴實現協作式 理解 44
4.3 事件風暴的工作方式 46
4.3.1 步驟1：明確領域事件 46
4.3.2 步驟2：創建事件描述 47
4.3.3 步驟3：查看描述并確定差距 48
4.3.4 步驟4：擴展領域理解力 49
4.3.5 步驟5：查看最終描述 50
4.4 事件風暴的好處 52
4.5 主持事件風暴會議 53
4.5.1 準備：收集必要的材料 用品 54
4.5.2 分享：溝通事件風暴會議 55
4.5.3 主持：進行事件風暴會議 56
4.5.4 總結：收集操作和步驟 56
4.5.5 跟進：會后建議 57
4.5.6 定制流程 57
4.6 小結 58
第三部分 定義候選API
第5章 明確API邊界 61
5.1 避免API邊界反模式 62
5.1.1 大型一體化API反模式 62
5.1.2 過載API反模式 62
5.1.3 輔助API反模式 63
5.2 有界上下文、子域和API 63
5.3 使用事件風暴探索API邊界 64
5.4 通過操作找到API邊界 67
5.5 為API命名并確定其范圍 68
5.6 小結 69
第6章 API建模 71
6.1 什么是API建模？ 72
6.2 API建模流程 74
6.2.1 步驟1：收集API配置文件摘要 74
6.2.2 步驟2：確定資源 75
6.2.3 步驟3：定義API分類法 77
6.2.4 步驟4：添加操作事件 79
6.2.5 步驟5：擴展操作的詳細信息 80
6.3 用序列圖驗證API模型 81
6.4 評估API的優先級和重用性 83
6.5 小結 84
第四部分 設計API
第7章 基于REST的API設計 87
7.1 什么是基于REST的API？ 88
7.1.1 REST是客戶-服務器體系結構 90
7.1.2 REST是以資源為中心的 90
7.1.3 REST是基于消息的 91
7.1.4 REST支持分層架構 91
7.1.5 REST支持按需編碼 93
7.1.6 超媒體控制 93
7.1.7 什么時候選擇REST 96
7.2 REST API設計流程 97
7.2.1 步驟1：設計資源URL路徑 97
7.2.2 步驟2：將API操作映射到HTTP方法上 99
7.2.3 步驟3：分配響應代碼 100
7.2.4 步驟4：記錄REST API設計 102
7.2.5 步驟5：分享并收集反饋 106
7.3 選擇一種表征格式 106
7.3.1 資源序列化 107
7.3.2 超媒體序列化 108
7.3.3 超媒體消息傳遞 109
7.3.4 語義超媒體消息傳遞 110
7.4 常見的REST設計模式 113
7.4.1 創建-讀取-更新-刪除 113
7.4.2 擴展資源生命周期支持 113
7.4.3 單例資源 114
7.4.4 后臺（隊列）作業 115
7.4.5 REST中的長期運行事務支持 116
7.5 小結 117
第8章 RPC和基于查詢的API設計 119
8.1 什么是基于RPC的API？ 120
8.1.1 gRPC 121
8.1.2 使用RPC時應該考慮的因素 122
8.2 RPC API設計流程 123
8.2.1 步驟1：確定RPC操作 123
8.2.2 步驟2：細化RPC操作 124
8.2.3 步驟3：記錄API設計 125
8.3 什么是基于查詢的API？ 126
8.3.1 了解OData 127
8.3.2 探索GraphQL 128
8.4 基于查詢的API設計流程 130
8.4.1 步驟1：設計資源和圖結構 130
8.4.2 步驟2：設計查詢和突變操作 131
8.4.3 步驟3：記錄API設計 132
8.5 小結 134
第9章 用于事件和流的異步API 135
9.1 API輪詢的問題 136
9.2 異步API創造新的可能性 137
9.3 回顧消息傳遞的基礎知識 138
9.3.1 消息傳遞的樣式和位置 139
9.3.2 消息的要素 140
9.3.3 了解消息代理 141
9.3.4 點對點消息分發（隊列） 142
9.3.5 扇出消息分發（主題） 143
9.3.6 消息流基礎知識 144
9.4 異步API樣式 145
9.4.1 使用Webhooks的服務器通知 146
9.4.2 使用服務器發送事件的服務器推送 147
9.4.3 通過WebSocket的雙向通知 148
9.4.4 gRPC流 149
9.4.5 選擇異步API樣式 151
9.5 設計異步API 151
9.5.1 命令消息 152
9.5.2 事件通知 152
9.5.3 事件承載的狀態轉移事件 153
9.5.4 事件批處理 155
9.5.5 事件排序 156
9.6 記錄異步API 156
9.7 小結 158
第五部分 優化API設計
第 10章 從API到微服務 161
10.1 什么是微服務？ 162
10.2 微服務降低協調成本 164
10.3 API產品和微服務之間的區別 165
10.4 權衡微服務的復雜性 165
10.4.1 自助服務基礎設施 166
10.4.2 獨立的發布周期 166
10.4.3 轉向單一團隊的所有權 166
10.4.4 組織結構和文化影響 166
10.4.5 數據所有權的轉移 167
10.4.6 分布式數據管理和治理 167
10.4.7 分布式系統的挑戰 168
10.4.8 彈性、故障轉移和分布式事務 168
10.4.9 重構和共享代碼帶來的挑戰 169
10.5 同步和異步的微服務 169
10.6 微服務架構的樣式 171
10.6.1 直接服務通信 171
10.6.2 基于API的編排 172
10.6.3 基于單元的架構 172
10.7 合理調整微服務的規模 173
10.8 API分解為微服務 174
10.8.1 步驟1：明確候選微服務 174
10.8.2 步驟2：將微服務添加到API序列圖中 176
10.8.3 步驟3：使用微服務設計畫布，以收集設計細節 177
10.8.4 其他微服務設計注意事項 178
10.9 過渡到微服務時的注意事項 179
10.10 小結 180
第 11章 改善開發者體驗 181
11.1 創建一個API模擬實現 182
11.1.1 API靜態模擬 183
11.1.2 API原型模擬 184
11.1.3 基于README的模擬 185
11.2 提供輔助庫和SDK 187
11.2.1 提供輔助庫的選項 187
11.2.2 對輔助庫版本化 188
11.2.3 輔助庫文檔和測試 188
11.3 為API提供CLI 189
11.4 小結 191
第 12章 API測試策略 193
12.1 驗收測試 194
12.2 自動化安全測試 194
12.3 運維監控 195
12.4 API契約測試 195
12.5 選擇工具，以加快測試速度 197
12.6 API測試的挑戰 197
12.7 讓API測試不可或缺 198
12.8 小結 199
第 13章 為API設計制作文檔 201
13.1 API文檔的重要性 202
13.2 API描述格式 202
13.2.1 OpenAPI規范 203
13.2.2 API Blueprint 205
13.2.3 RAML 207
13.2.4 JSON Schema 211
13.2.5 使用ALPS的API配置文件 212
13.2.6 使用APIs.json改進API發現功能 213
13.3 使用代碼示例擴展文檔 215
13.3.1 先寫好入門代碼示例 215
13.3.2 使用工作流示例擴展文檔 216
13.3.3 錯誤案例和生產就緒的示例 217
13.4 從參考文檔到開發者門戶網站 217
13.4.1 通過開發者門戶網站提高API采用率 218
13.4.2 優秀的開發者門戶網站的要素 218
13.5 有效的API文檔 219
13.5.1 問題1：你的API如何解決我的問題？ 220
13.5.2 問題2：每個API操作都支持什么功能？ 220
13.5.3 問題3：我如何開始使用API？ 220
13.5.4 技術文檔撰寫人在API文檔中的角色 221
13.6 最小可行的門戶 222
13.6.1 第 1個階段：最小可行的門戶 222
13.6.2 第 2個階段：改進 223
13.6.3 第3個階段：專注于增長 224
13.7 用來制作開發者門戶網站的工具和框架 224
13.8 小結 225
第 14章 為變更而設計 227
14.1 變更對現有API的影響 227
14.1.1 進行API設計差距分析 228
14.1.2 確定什么最適合API消費者 228
14.1.3 變更策略 229
14.1.4 變更管理是建立在信任之上的 230
14.2 API版本控制策略 230
14.2.1 常見的非破壞性變更 231
14.2.2 不兼容的變更 231
14.2.3 API版本和修訂版本 232
14.2.4 API版本控制方法 233
14.2.5 API版本的商業考慮因素 234
14.3 棄用API 234
14.3.1 制訂棄用策略 235
14.3.2 宣布棄用 235
14.4 創建一個API穩定性契約 236
14.5 小結 237
第 15章 保護API 239
15.1 危害API的潛在因素 239
15.2 基本的API保護實踐 240
15.3 API保護的組件 242
15.3.1 API網關 242
15.3.2 APIM層 242
15.3.3 服務網格 243
15.3.4 WAF 244
15.3.5 內容分發網絡 244
15.3.6 智能API保護 244
15.4 API網關拓撲結構 245
15.4.1 APIM托管選項 245
15.4.2 API網絡流量注意事項 248
15.4.3 拓撲結構1：API網關直連到API服務器 248
15.4.4 拓撲結構2：API網關路由到服務 249
15.4.5 拓撲結構3：多個API網關實例 250
15.5 身份和訪問管理 251
15.5.1 密碼和API密鑰 251
15.5.2 API令牌 251
15.5.3 引用傳遞與值傳遞的API令牌 253
15.5.4 OAuth 2.0和OpenID Connect 253
15.6 構建內部API網關之前的注意事項 255
15.6.1 原因1：API安全性是一個不斷變化的目標 255
15.6.2 原因2：需要的時間比預期的更長 255
15.6.3 原因3：預期的表現需要時間 256
15.6.4 輔助庫怎么樣？ 256
15.7 小結 257
第 16章 繼續API設計旅程 259
16.1 建立API樣式指南 259
16.1.1 鼓勵遵守樣式指南的方法 260
16.1.2 選擇樣式指南的“基調” 261
16.1.3 啟動API樣式指南的入門技巧 261
16.1.4 支持多種API樣式 262
16.2 進行API設計審查 262
16.2.1 從文檔審查開始 263
16.2.2 檢查標準和設計是否對齊 264
16.2.3 審查測試覆蓋率 264
16.2.4 添加試用支持 265
16.3 鼓勵重用文化 265
16.4 旅程才剛剛開始 266
附錄A HTTP入門知識 267
A.1 HTTP概述 267
A.2 統一資源定位符 268
A.3 HTTP請求 269
A.4 HTTP響應 270
A.5 常見HTTP方法 271
A.6 HTTP響應代碼 272
A.7 內容協商 273
A.8 緩存控制 275
A.9 條件性請求 276
A.10 HTTP中的并發控制 278
A.11 小結 280
新書資訊