API Design Patterns

9.8 MB·English

by  JJ Geewax

inside 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