Table Of Contentinside front cover Page: 2
API Design Patterns Page: 3
Copyright Page: 4
dedication Page: 5
contents Page: 6
front matter Page: 8
foreword Page: 8
preface Page: 8
acknowledgments Page: 9
about this book Page: 9
Who should read this book Page: 9
How this book is organized: A roadmap Page: 9
About the code Page: 11
Live book discussion forum Page: 12
Other online resources Page: 12
about the author Page: 12
about the cover illustration Page: 12
Part 1 Introduction Page: 13
1 Introduction to APIs Page: 14
1.1 What are web APIs? Page: 14
1.2 Why do APIs matter? Page: 14
1.3 What are resource-oriented APIs? Page: 15
1.4 What makes an API “good”? Page: 16
1.4.1 Operational Page: 16
1.4.2 Expressive Page: 16
1.4.3 Simple Page: 17
1.4.4 Predictable Page: 18
Summary Page: 18
2 Introduction to API design patterns Page: 19
2.1 What are API design patterns? Page: 19
2.2 Why are API design patterns important? Page: 20
2.3 Anatomy of an API design pattern Page: 21
2.3.1 Name and synopsis Page: 21
2.3.2 Motivation Page: 21
2.3.3 Overview Page: 22
2.3.4 Implementation Page: 22
2.3.5 Trade-offs Page: 22
2.4 Case study: Twapi, a Twitter-like API Page: 23
2.4.1 Overview Page: 23
2.4.2 Listing messages Page: 23
2.4.3 Exporting data Page: 24
Summary Page: 26
Part 2 Design principles Page: 27
3 Naming Page: 28
3.1 Why do names matter? Page: 28
3.2 What makes a name “good”? Page: 28
3.2.1 Expressive Page: 28
3.2.2 Simple Page: 28
3.2.3 Predictable Page: 29
3.3 Language, grammar, and syntax Page: 29
3.3.1 Language Page: 29
3.3.2 Grammar Page: 30
3.3.3 Syntax Page: 31
3.4 Context Page: 32
3.5 Data types and units Page: 32
3.6 Case study: What happens when you choose bad names? Page: 33
3.7 Exercises Page: 34
Summary Page: 34
4 Resource scope and hierarchy Page: 35
4.1 What is resource layout? Page: 35
4.1.1 Types of relationships Page: 35
4.1.2 Entity relationship diagrams Page: 37
4.2 Choosing the right relationship Page: 37
4.2.1 Do you need a relationship at all? Page: 37
4.2.2 References or in-line data Page: 38
4.2.3 Hierarchy Page: 38
4.3 Anti-patterns Page: 39
4.3.1 Resources for everything Page: 39
4.3.2 Deep hierarchies Page: 40
4.3.3 In-line everything Page: 40
4.4 Exercises Page: 40
Summary Page: 41
5 Data types and defaults Page: 42
5.1 Introduction to data types Page: 42
5.1.1 Missing vs. null Page: 42
5.2 Booleans Page: 43
5.3 Numbers Page: 44
5.3.1 Bounds Page: 44
5.3.2 Default values Page: 45
5.3.3 Serialization Page: 45
5.4 Strings Page: 45
5.4.1 Bounds Page: 46
5.4.2 Default values Page: 46
5.4.3 Serialization Page: 46
5.5 Enumerations Page: 47
5.6 Lists Page: 47
5.6.1 Atomicity Page: 48
5.6.2 Bounds Page: 48
5.6.3 Default values Page: 48
5.7 Maps Page: 49
5.7.1 Bounds Page: 50
5.7.2 Default values Page: 50
5.8 Exercises Page: 50
Summary Page: 50
Part 3 Fundamentals Page: 51
6 Resource identification Page: 52
6.1 What is an identifier? Page: 52
6.2 What makes a good identifier? Page: 52
6.2.1 Easy to use Page: 52
6.2.2 Unique Page: 52
6.2.3 Permanent Page: 52
6.2.4 Fast and easy to generate Page: 53
6.2.5 Unpredictable Page: 53
6.2.6 Readable, shareable, and verifiable Page: 53
6.2.7 Informationally dense Page: 53
6.3 What does a good identifier look like? Page: 54
6.3.1 Data type Page: 54
6.3.2 Character set Page: 54
6.3.3 Identifier format Page: 54
6.3.4 Checksums Page: 55
6.3.5 Resource type Page: 55
6.3.6 Hierarchy and uniqueness scope Page: 55
6.4 Implementation Page: 56
6.4.1 Size Page: 56
6.4.2 Generation Page: 56
6.4.3 Tomb-stoning Page: 57
6.4.4 Checksum Page: 57
6.4.5 Database storage Page: 58
6.5 What about UUIDs? Page: 59
6.6 Exercises Page: 59
Summary Page: 59
7 Standard methods Page: 61
7.1 Motivation Page: 61
7.2 Overview Page: 61
7.3 Implementation Page: 62
7.3.1 Which methods should be supported? Page: 62
7.3.2 Idempotence and side effects Page: 62
7.3.3 Get Page: 63
7.3.4 List Page: 63
7.3.5 Create Page: 64
7.3.6 Update Page: 65
7.3.7 Delete Page: 65
7.3.8 Replace Page: 66
7.3.9 Final API definition Page: 67
7.4 Trade-offs Page: 67
7.5 Exercises Page: 68
Summary Page: 68
8 Partial updates and retrievals Page: 69
8.1 Motivation Page: 69
8.1.1 Partial retrieval Page: 69
8.1.2 Partial update Page: 69
8.2 Overview Page: 70
8.3 Implementation Page: 70
8.3.1 Transport Page: 71
8.3.2 Maps and nested interfaces Page: 71
8.3.3 Repeated fields Page: 72
8.3.4 Default values Page: 73
8.3.5 Implicit field masks Page: 74
8.3.6 Updating dynamic data structures Page: 74
8.3.7 Invalid fields Page: 75
8.3.8 Final API definition Page: 75
8.4 Trade-offs Page: 75
8.4.1 Universal support Page: 76
8.4.2 Alternative implementations Page: 76
8.5 Exercises Page: 76
Summary Page: 76
9 Custom methods Page: 77
9.1 Motivation Page: 77
9.1.1 Why not just standard methods? Page: 77
9.2 Overview Page: 78
9.3 Implementation Page: 79
9.3.1 Side effects Page: 79
9.3.2 Resources vs. collections Page: 79
9.3.3 Stateless custom methods Page: 80
9.3.4 Final API definition Page: 81
9.4Trade-offs Page: 81
9.5 Exercises Page: 81
Summary Page: 81
10 Long-running operations Page: 83
10.1 Motivation Page: 83
10.2 Overview Page: 83
10.3 Implementation Page: 84
10.3.1 What does an LRO look like? Page: 84
10.3.2 Resource hierarchy Page: 85
10.3.3 Resolution Page: 85
10.3.4 Error handling Page: 87
10.3.5 Monitoring progress Page: 88
10.3.6 Canceling operations Page: 88
10.3.7 Pausing and resuming operations Page: 89
10.3.8 Exploring operations Page: 89
10.3.9 Persistence Page: 90
10.3.10 Final API definition Page: 90
10.4 Trade-offs Page: 91
10.5 Exercises Page: 91
Summary Page: 91
11 Rerunnable jobs Page: 92
11.1 Motivation Page: 92
11.2 Overview Page: 92
11.3 Implementation Page: 93
11.3.1 Job resources Page: 93
11.3.2 The custom run method Page: 94
11.3.3 Job execution resources Page: 94
11.3.4 Final API definition Page: 95
11.4 Trade-offs Page: 96
11.5 Exercises Page: 96
Summary Page: 96
Part 4 Resource relationships Page: 97
12 Singleton sub-resources Page: 98
12.1 Motivation Page: 98
12.1.1 Why should we use a singleton sub-resource? Page: 98
12.2 Overview Page: 99
12.3 Implementation Page: 99
12.3.1 Standard methods Page: 99
12.3.2 Resetting Page: 100
12.3.3 Hierarchy Page: 100
12.3.4 Final API definition Page: 100
12.4 Trade-offs Page: 101
12.4.1 Atomicity Page: 101
12.4.2 Exactly one sub-resource Page: 101
12.5 Exercises Page: 101
Summary Page: 101
13 Cross references Page: 102
13.1 Motivation Page: 102
13.2 Overview Page: 102
13.3 Implementation Page: 102
13.3.1 Reference field name Page: 102
13.3.2 Data integrity Page: 102
13.3.3 Value vs. reference Page: 103
13.3.4 Final API definition Page: 104
13.4 Trade-offs Page: 104
11.5 Exercises Page: 104
Summary Page: 104
14 Association resources Page: 105
14.1 Motivation Page: 105
14.2 Overview Page: 105
14.2.1 Association alias methods Page: 105
14.3 Implementation Page: 106
14.3.1 Naming the association resource Page: 106
14.3.2 Standard method behavior Page: 106
14.3.3 Uniqueness Page: 106
14.3.4 Read-only fields Page: 106
14.3.5 Association alias methods Page: 107
14.3.6 Referential integrity Page: 107
14.3.7 Final API definition Page: 107
14.4 Trade-offs Page: 108
14.4.1 Complexity Page: 108
14.4.2 Separation of associations Page: 108
14.5 Exercises Page: 108
Summary Page: 109
15 Add and remove custom methods Page: 110
15.1 Motivation Page: 110
15.2 Overview Page: 110
15.3 Implementation Page: 110
15.3.1 Listing associated resources Page: 111
15.3.2 Data integrity Page: 111
15.3.3 Final API definition Page: 111
15.4 Trade-offs Page: 112
15.4.1 Nonreciprocal relationship Page: 112
15.4.2 Relationship metadata Page: 112
15.5 Exercises Page: 112
Summary Page: 112
16 Polymorphism Page: 113
16.1 Motivation Page: 113
16.2 Overview Page: 113
16.3 Implementation Page: 113
16.3.1 Deciding when to use polymorphic resources Page: 113
16.3.2 Polymorphic structure Page: 114
16.3.3 Polymorphic behavior Page: 116
16.3.4 Why not polymorphic methods? Page: 116
16.3.5 Final API definition Page: 117
16.4 Trade-offs Page: 117
16.5 Exercises Page: 117
Summary Page: 117
Part 5 Collective operations Page: 118
17 Copy and move Page: 119
17.1 Motivation Page: 119
17.2 Overview Page: 119
17.3 Implementation Page: 119
17.3.1 Identifiers Page: 119
17.3.2 Child resources Page: 121
17.3.3 Related resources Page: 121
17.3.4 External data Page: 122
17.3.5 Inherited metadata Page: 123
17.3.6 Atomicity Page: 123
17.3.7 Final API definition Page: 124
17.4 Trade-offs Page: 124
17.5 Exercises Page: 125
Summary Page: 125
18 Batch operations Page: 126
18.1 Motivation Page: 126
18.2 Overview Page: 126
18.3 Implementation Page: 126
18.3.1 Atomicity Page: 127
18.3.2 Operation on the collection Page: 127
18.3.3 Ordering of results Page: 127
18.3.4 Common fields Page: 127
18.3.5 Operating across parents Page: 128
18.3.6 Batch Get Page: 129
18.3.7 Batch Delete Page: 129
18.3.8 Batch Create Page: 130
18.3.9 Batch Update Page: 131
18.3.10 Final API definition Page: 131
18.4 Trade-offs Page: 132
18.5 Exercises Page: 132
Summary Page: 132
19 Criteria-based deletion Page: 133
19.1 Motivation Page: 133
19.2 Overview Page: 133
19.3 Implementation Page: 133
19.3.1 Filtering results Page: 134
19.3.2 Validation only by default Page: 134
19.3.3 Result count Page: 134
19.3.4 Result sample set Page: 135
19.3.5 Consistency Page: 135
19.3.6 Final API definition Page: 135
19.4 Trade-offs Page: 136
19.5 Exercises Page: 136
Summary Page: 136
20 Anonymous writes Page: 137
20.1 Motivation Page: 137
20.2 Overview Page: 137
20.3 Implementation Page: 137
20.3.1 Consistency Page: 138
20.3.2 Final API definition Page: 139
20.4 Trade-offs Page: 139
20.5 Exercises Page: 139
Summary Page: 139
21 Pagination Page: 140
21.1 Motivation Page: 140
21.2 Overview Page: 140
21.3 Implementation Page: 140
21.3.1 Page size Page: 141
21.3.2 Page tokens Page: 141
21.3.3 Total count Page: 143
21.3.4 Paging inside resources Page: 143
21.3.5 Final API definition Page: 143
21.4 Trade-offs Page: 143
21.4.1 Bi-directional paging Page: 143
21.4.2 Arbitrary windows Page: 144
21.5 Anti-pattern: Offsets and limits Page: 144
21.6 Exercises Page: 144
Summary Page: 144
22 Filtering Page: 145
22.1 Motivation Page: 145
22.2 Overview Page: 145
22.3 Implementation Page: 146
22.3.1 Structure Page: 146
22.3.2 Filter syntax and behavior Page: 147
22.3.3 Final API definition Page: 150
22.4 Trade-offs Page: 150
22.5 Exercises Page: 150
Summary Page: 150
23 Importing and exporting Page: 151
23.1 Motivation Page: 151
23.2 Overview Page: 151
23.3 Implementation Page: 152
23.3.1 Import and export methods Page: 152
23.3.2 Interacting with storage systems Page: 152
23.3.3 Converting between resources and bytes Page: 153
23.3.4 Consistency Page: 154
23.3.5 Identifiers and collisions Page: 155
23.3.6 Handling related resources Page: 155
23.3.7 Failures and retries Page: 156
23.3.8 Filtering and field masks Page: 157
23.3.9 Final API definition Page: 157
23.4 Trade-offs Page: 158
23.5 Exercises Page: 158
Summary Page: 158
Part 6 Safety and security Page: 160
24 Versioning and compatibility Page: 161
24.1 Motivation Page: 161
24.2 Overview Page: 161
24.2.1 What is compatibility? Page: 161
24.2.2 Defining backward compatibility Page: 162
24.3 Implementation Page: 165
24.3.1 Perpetual stability Page: 165
24.3.2 Agile instability Page: 166
24.3.3 Semantic versioning Page: 167
24.4 Trade-offs Page: 168
24.4.1 Granularity vs. simplicity Page: 169
24.4.2 Stability vs. new functionality Page: 169
24.4.3 Happiness vs. ubiquity Page: 170
24.5 Exercises Page: 170
Summary Page: 171
25 Soft deletion Page: 172
25.1 Motivation Page: 172
25.2 Overview Page: 172
25.3 Implementation Page: 172
25.3.1 Deleted designation Page: 173
25.3.2 Modifying standard methods Page: 173
25.3.3 Undeleting Page: 174
25.3.4 Expunging Page: 174
25.3.5 Expiration Page: 175
25.3.6 Referential integrity Page: 175
25.3.7 Effects on other methods Page: 176
25.3.8 Adding soft delete across versions Page: 176
25.3.9 Final API definition Page: 176
25.4 Trade-offs Page: 176
25.5 Exercises Page: 176
Summary Page: 177
26 Request deduplication Page: 178
26.1 Motivation Page: 178
26.2 Overview Page: 178
26.3 Implementation Page: 178
26.3.1 Request identifier Page: 179
26.3.2 Response caching Page: 179
26.3.3 Consistency Page: 179
26.3.4 Request ID collisions Page: 180
26.3.5 Cache expiration Page: 180
26.3.6 Final API definition Page: 181
26.4 Trade-offs Page: 181
26.5 Exercises Page: 181
Summary Page: 181
27 Request validation Page: 182
27.1 Motivation Page: 182
27.2 Overview Page: 182
27.3 Implementation Page: 182
27.3.1 External dependencies Page: 183
27.3.2 Special side effects Page: 183
27.3.3 Final API definition Page: 184
27.4 Trade-offs Page: 184
27.5 Exercises Page: 184
Summary Page: 184
28 Resource revisions Page: 185
28.1 Motivation Page: 185
28.2 Overview Page: 185
28.3 Implementation Page: 185
28.3.1 Revision identifiers Page: 186
28.3.2 Creating revisions Page: 186
28.3.3 Retrieving specific revisions Page: 187
28.3.4 Listing revisions Page: 188
28.3.5 Restoring a previous revision Page: 188
28.3.6 Deleting revisions Page: 189
28.3.7 Handling child resources Page: 190
28.3.8 Final API definition Page: 190
28.4 Trade-offs Page: 190
28.5 Exercises Page: 190
Summary Page: 191
29 Request retrial Page: 192
29.1 Motivation Page: 192
29.2 Overview Page: 192
29.2.1 Client-side retry timing Page: 192
29.2.2 Server-specified retry timing Page: 193
29.3 Implementation Page: 193
29.3.1 Retry eligibility Page: 193
29.3.2 Exponential back-off Page: 194
29.3.3 Retry After Page: 195
29.3.4 Final API definition Page: 196
29.4 Trade-offs Page: 196
29.5 Exercises Page: 196
Summary Page: 196
30 Request authentication Page: 197
30.1 Motivation Page: 197
30.1.1 Origin Page: 197
30.1.2 Integrity Page: 197
30.1.3 Nonrepudiation Page: 197
30.2 Overview Page: 198
30.3 Implementation Page: 198
30.3.1 Credential generation Page: 198
30.3.2 Registration and credential exchange Page: 198
30.3.3 Generating and verifying raw signatures Page: 199
30.3.4 Request fingerprinting Page: 199
30.3.5 Including the signature Page: 200
30.3.6 Authenticating requests Page: 201
30.3.7 Final API definition Page: 202
30.4 Trade-offs Page: 202
30.5 Exercises Page: 202
Summary Page: 202
index Page: 203
Description:"A concept-rich book on API design patterns. Deeply engrossing and fun to read." - Satej Sahu, Honeywell API Design Patterns lays out a set of design principles for building internal and public-facing APIs. In API Design Patterns you will learn: Guiding principles for API patterns Fundamentals of resource layout and naming Handling data types for any programming language Standard methods that ensure predictability Field masks for targeted partial updates Authentication and validation methods for secure APIs Collective operations for moving, managing, and deleting data Advanced patterns for special interactions and data transformations API Design Patterns reveals best practices for building stable, user-friendly APIs. These design patterns can be applied to solve common API problems and flexibly altered to fit specific needs. Hands-on examples and relevant cases illustrate patterns for API fundamentals, advanced functionalities, and uncommon scenarios. Purchase of the print book includes a free eBook in PDF, Kindle, and ePub formats from Manning Publications. About the technology APIs are contracts that define how applications, services, and components communicate. API design patterns provide a shared set of best practices, specifications and standards that ensure APIs are reliable and simple for other developers. This book collects and explains the most important patterns from both the API design community and the experts at Google. About the book API Design Patterns lays out a set of principles for building internal and public-facing APIs. Google API expert JJ Geewax presents patterns that ensure your APIs are consistent, scalable, and flexible. You’ll improve the design of the most common APIs, plus discover techniques for tricky edge cases. Precise illustrations, relevant examples, and detailed scenarios make every pattern clear and easy to understand. What's inside Guiding principles for API patterns Fundamentals of resource layout and naming Advanced patterns for special interactions and data transformations A detailed case-study on building an API and adding features About the reader For developers building web and internal APIs in any language. About the author JJ Geewax is a software engineer at Google, focusing on Google Cloud Platform, API design, and real-time payment systems. He is also the author of Manning’s Google Cloud Platform in Action. Table of Contents PART 1 INTRODUCTION 1 Introduction to APIs 2 Introduction to API design patterns PART 2 DESIGN PRINCIPLES 3 Naming 4 Resource scope and hierarchy 5 Data types and defaults PART 3 FUNDAMENTALS 6 Resource identification 7 Standard methods 8 Partial updates and retrievals 9 Custom methods 10 Long-running operations 11 Rerunnable jobs PART 4 RESOURCE RELATIONSHIPS 12 Singleton sub-resources 13 Cross references 14 Association resources 15 Add and remove custom methods 16 Polymorphism PART 5 COLLECTIVE OPERATIONS 17 Copy and move 18 Batch operations 19 Criteria-based deletion 20 Anonymous writes 21 Pagination 22 Filtering 23 Importing and exporting PART 6 SAFETY AND SECURITY 24 Versioning and compatibility 25 Soft deletion 26 Request deduplication 27 Request validation 28 Resource revisions 29 Request retrial 30 Request authentication