API設計模式

目    錄

第Ⅰ部分  基礎知識概述

第1章　API基礎知識   3

1.1  從本地接口到遠程API   3

1.1.1  分佈式系統和遠程API概述   4

1.1.2  遠程API：通過集成協議訪問服務   5

1.1.3  API的重要性   6

1.2  API設計中的決策驅動因素   11

1.2.1  API的成功要素   11

1.2.2  API設計有何不同   12

1.2.3  API設計難在哪裡   12

1.2.4  架構方面的重要需求   14

1.2.5　開發者體驗   15

1.3 遠程API的領域模型   16

1.3.1  通信參與者   16

1.3.2  API端點提供描述操作的API契約   17

1.3.3  消息是對話的組成部分   17

1.3.4  消息結構和表示   18

1.3.5  API契約   19

1.3.6  全書使用的領域模型   20

1.4  本章小結   20

第2章　Lakeside Mutual案例研究   23

2.1  業務背景和要求   23

2.1.1  用戶故事和期望的系統質量   23

2.1.2  分析級別的領域模型   24

2.2  架構概述   26

2.2.1  系統上下文   26

2.2.2  應用程序架構   27

2.3  API設計活動   29

2.4  目標API規範   29

2.5  本章小結   30

第3章　API決策敘述   33

3.1  前奏：模式作為決策選項，設計驅動力作為決策標準   33

3.2  API的基礎性決策和模式   35

3.2.1  API可見性   36

3.2.2  API集成類型   39

3.2.3  API文檔   41

3.3  API角色和職責的相關決策   43

3.3.1  端點的架構角色   44

3.3.2  剖析各類信息持有者角色   46

3.3.3　定義操作職責   50

3.4  選擇消息表示模式   52

3.4.1  表示元素的扁平結構與嵌套結構   54

3.4.2  元素構造型   58

3.5  插敘：Lakeside Mutual案例中的職責和結構模式   61

3.6  API質量治理的相關決策   62

3.6.1  API客戶端的識別和身份驗證   63

3.6.2  對API的使用情況進行計量和計費   65

3.6.3  防止API客戶端過度使用API   67

3.6.4  明確規定質量目標和處罰機制   69

3.6.5  報告和處理錯誤   70

3.6.6  顯式上下文表示   71

3.7  API質量改進的相關決策   73

3.7.1  分頁   73

3.7.2  避免非必要數據傳輸的其他手段   76

3.7.3  處理消息中的引用數據   79

3.8  API演進的相關決策   81

3.8.1  版本控制和兼容性管理   83

3.8.2  版本發布和停用的相關策略   85

3.9  插敘：Lakeside Mutual案例中的質量和演進模式   88

3.10  本章小結   90

第Ⅱ部分  模式

第4章　模式語言簡介   95

4.1  定位和範圍   95

4.2  使用模式的原因和方法   97

4.3  模式一覽   98

4.3.1  結構組織：按範圍查找模式   98

4.3.2  主題分類：查找模式   99

4.3.3  時間維度：遵循設計完善階段   100

4.3.4  瀏覽方式：從Map到MAP   101

4.4  基礎模式：API可見性和集成類型   102

4.4.1  Frontend Integration模式   103

4.4.2  Backend Integration模式   104

4.4.3  Public API模式   105

4.4.4  Community API模式   106

4.4.5  Solution-Internal API模式   108

4.4.6  基礎模式小結   109

4.5  基本結構模式   109

4.5.1  Atomic Parameter模式   110

4.5.2  Atomic Parameter List模式   112

4.5.3  Parameter Tree模式   114

4.5.4  Parameter Forest模式   116

4.5.5  基本結構模式小結   118

4.6  本章小結   119

第5章　定義端點類型和操作   121

5.1  API角色和職責簡介   121

5.1.1  設計挑戰和期望質量   122

5.1.2  本章討論的模式   123

5.2  端點角色(服務粒度)   125

5.2.1  Processing Resource模式   125

5.2.2  Information Holder Resource模式   132

5.2.3  Operational Data Holder模式   138

5.2.4  Master Data Holder模式   142

5.2.5  Reference Data Holder模式   146

5.2.6  Link Lookup Resource模式   149

5.2.7  Data Transfer Resource模式   154

5.3  操作職責   161

5.3.1  State Creation Operation模式   162

5.3.2  Retrieval Operation模式   167

5.3.3  State Transition Operation模式   171

5.3.4  Computation Function模式   180

5.4  本章小結   186

第6章　設計請求消息和響應消息表示   189

6.1  消息表示設計簡介   189

6.1.1  消息表示設計面臨的挑戰   190

6.1.2  本章討論的模式   190

6.2  元素構造型   191

6.2.1  Data Element模式   192

6.2.2  Metadata Element模式   196

6.2.3  Id Element模式   203

6.2.4  Link Element模式   207

6.3  特殊用途的表示元素   212

6.3.1  API Key模式   213

6.3.2  Error Report模式   217

6.3.3  Context Representation模式   221

6.4  本章小結   231

第7章　優化消息設計以改善質量   233

7.1  API質量簡介   233

7.1.1  改善API質量面臨的挑戰   234

7.1.2  本章討論的模式   234

7.2  消息粒度   236

7.2.1  Embedded Entity模式   237

7.2.2  Linked Information Holder模式   241

7.3  由客戶端決定獲取哪些消息內容(響應塑造)   245

7.3.1  Pagination模式   246

7.3.2  Wish List模式   253

7.3.3  Wish Template模式   256

7.4  消息交換優化(對話效率)   260

7.4.1  Conditional Request模式   261

7.4.2  Request Bundle模式   265

7.5  本章小結   269

第8章　API演進   271

8.1  API演進簡介   271

8.1.1  API演進面臨的挑戰   271

8.1.2  本章討論的模式   274

8.2  版本控制和兼容性管理   274

8.2.1  Version IDentifier模式   275

8.2.2  Semantic Versioning模式   280

8.3  生命周期管理保證   284

8.3.1  Experimental Preview模式   284

8.3.2  Aggressive Obsolescence模式   287

8.3.3  Limited Lifetime Guarantee模式   291

8.3.4  Two in Production模式   294

8.4  本章小結   298

第9章　編寫和傳達API契約   301

9.1  API文檔簡介   301

9.1.1  編寫API文檔時面臨的挑戰   301

9.1.2  本章討論的模式   303

9.2  文檔模式   303

9.2.1  API Description模式   304

9.2.2  Pricing Plan模式   309

9.2.3  Rate Limit模式   313

9.2.4  Service Level Agreement模式   316

9.3  本章小結   320

第Ⅲ部分  實踐應用

第10章　實際的模式案例   325

10.1  瑞士抵押貸款業務的大規模流程集成   325

10.1.1  業務背景和領域   325

10.1.2  技術方面的挑戰   326

10.1.3  API的角色和狀態   327

10.1.4  模式使用和實現   328

10.1.5  回顧與展望   333

10.2  建築施工領域的報價和訂購流程   335

10.2.1  業務背景和領域   335

10.2.2  技術方面的挑戰   336

10.2.3  API的角色和狀態   336

10.2.4  模式使用和實現   338

10.2.5  回顧與展望   339

10.3  本章小結   340

第11章　結語   341

11.1  簡要回顧   341

11.2  API研究：模式重構、微服務領域特定語言及其他   342

11.3  未來展望   343

11.4  其他資源   344

11.5  寫在最後   344

附錄A　端點識別和模式選擇指南   345

附錄B　Lakeside Mutual案例的實現   353

附錄C　微服務領域特定語言   361