Web API設計原則通過API和微服務實現(xiàn)價值交付

第 一部分 Web API設計簡介
第 1章 API設計原則　3
1.1 Web API設計要素　4
1.1.1 業(yè)務功能　4
1.1.2 產品思維　4
1.1.3 開發(fā)者體驗　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章 協(xié)作式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設計優(yōu)先的方法　19
2.4 API設計優(yōu)先并保持敏捷　20
2.4.1 重新審視敏捷宣言　21
2.4.2 API設計優(yōu)先的敏捷性　21
2.5 對齊-定義-設計-優(yōu)化流程　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 克服任務用例的挑戰(zhàn)　36
3.7.1 挑戰(zhàn)1：任務用例過于詳細　36
3.7.2 挑戰(zhàn)2：任務用例以功能為中心　36
3.7.3 挑戰(zhàn)3：任務用例需要額外的用戶上下文　37
3.8 收集任務用例的技巧　37
3.9 現(xiàn)實世界中的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 通過事件風暴實現(xiàn)協(xié)作式 理解　44
4.3 事件風暴的工作方式　46
4.3.1 步驟1：明確領域事件　46
4.3.2 步驟2：創(chuàng)建事件描述　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的優(yōu)先級和重用性　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 創(chuàng)建-讀取-更新-刪除　113
7.4.2 擴展資源生命周期支持　113
7.4.3 單例資源　114
7.4.4 后臺（隊列）作業(yè)　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創(chuàng)造新的可能性　137
9.3 回顧消息傳遞的基礎知識　138
9.3.1 消息傳遞的樣式和位置　139
9.3.2 消息的要素　140
9.3.3 了解消息代理　141
9.3.4 點對點消息分發(fā)（隊列）　142
9.3.5 扇出消息分發(fā)（主題）　143
9.3.6 消息流基礎知識　144
9.4 異步API樣式　145
9.4.1 使用Webhooks的服務器通知　146
9.4.2 使用服務器發(fā)送事件的服務器推送　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 事件承載的狀態(tài)轉移事件　153
9.5.4 事件批處理　155
9.5.5 事件排序　156
9.6 記錄異步API　156
9.7 小結　158
第五部分 優(yōu)化API設計
第 10章 從API到微服務　161
10.1 什么是微服務？　162
10.2 微服務降低協(xié)調成本　164
10.3 API產品和微服務之間的區(qū)別　165
10.4 權衡微服務的復雜性　165
10.4.1 自助服務基礎設施　166
10.4.2 獨立的發(fā)布周期　166
10.4.3 轉向單一團隊的所有權　166
10.4.4 組織結構和文化影響　166
10.4.5 數據所有權的轉移　167
10.4.6 分布式數據管理和治理　167
10.4.7 分布式系統(tǒng)的挑戰(zhàn)　168
10.4.8 彈性、故障轉移和分布式事務　168
10.4.9 重構和共享代碼帶來的挑戰(zhàn)　169
10.5 同步和異步的微服務　169
10.6 微服務架構的樣式　171
10.6.1 直接服務通信　171
10.6.2 基于API的編排　172
10.6.3 基于單元的架構　172
10.7 合理調整微服務的規(guī)?！?73
10.8 API分解為微服務　174
10.8.1 步驟1：明確候選微服務　174
10.8.2 步驟2：將微服務添加到API序列圖中　176
10.8.3 步驟3：使用微服務設計畫布，以收集設計細節(jié)　177
10.8.4 其他微服務設計注意事項　178
10.9 過渡到微服務時的注意事項　179
10.10 小結　180
第 11章 改善開發(fā)者體驗　181
11.1 創(chuàng)建一個API模擬實現(xiàn)　182
11.1.1 API靜態(tài)模擬　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 運維監(jiān)控　195
12.4 API契約測試　195
12.5 選擇工具，以加快測試速度　197
12.6 API測試的挑戰(zhàn)　197
12.7 讓API測試不可或缺　198
12.8 小結　199
第 13章 為API設計制作文檔　201
13.1 API文檔的重要性　202
13.2 API描述格式　202
13.2.1 OpenAPI規(guī)范　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發(fā)現(xiàn)功能　213
13.3 使用代碼示例擴展文檔　215
13.3.1 先寫好入門代碼示例　215
13.3.2 使用工作流示例擴展文檔　216
13.3.3 錯誤案例和生產就緒的示例　217
13.4 從參考文檔到開發(fā)者門戶網站　217
13.4.1 通過開發(fā)者門戶網站提高API采用率　218
13.4.2 優(yōu)秀的開發(fā)者門戶網站的要素　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 用來制作開發(fā)者門戶網站的工具和框架　224
13.8 小結　225
第 14章 為變更而設計　227
14.1 變更對現(xiàn)有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版本的商業(yè)考慮因素　234
14.3 棄用API　234
14.3.1 制訂棄用策略　235
14.3.2 宣布棄用　235
14.4 創(chuàng)建一個API穩(wěn)定性契約　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 內容分發(fā)網絡　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：預期的表現(xiàn)需要時間　256
15.6.4 輔助庫怎么樣？　256
15.7 小結　257
第 16章 繼續(xù)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 統(tǒng)一資源定位符　268
A.3 HTTP請求　269
A.4 HTTP響應　270
A.5 常見HTTP方法　271
A.6 HTTP響應代碼　272
A.7 內容協(xié)商　273
A.8 緩存控制　275
A.9 條件性請求　276
A.10 HTTP中的并發(fā)控制　278
A.11 小結　280