API Design Patterns

API Design Patterns....1 brief contents....9 contents....11 foreword....23 preface....25 acknowledgments....27 about this book....29 Who should read this book....29 How this book is organized: A roadmap....29 About the code....33 Live book discussion forum....34 Other online resources....34 about the author....35 about the cover illustration....36 Part 1—Introduction....37 1 Introduction to APIs....39 1.1 What are web APIs?....39 1.2 Why do APIs matter?....41 1.3 What are resource-oriented APIs?....42 1.4 What makes an API “good”?....44 1.4.1 Operational....45 1.4.2 Expressive....45 1.4.3 Simple....46 1.4.4 Predictable....48 Summary....49 2 Introduction to API design patterns....50 2.1 What are API design patterns?....50 2.2 Why are API design patterns important?....53 2.3 Anatomy of an API design pattern....55 2.3.1 Name and synopsis....55 2.3.2 Motivation....55 2.3.3 Overview....56 2.3.4 Implementation....57 2.3.5 Trade-offs....57 2.4 Case study: Twapi, a Twitter-like API....58 2.4.1 Overview....58 2.4.2 Listing messages....59 2.4.3 Exporting data....62 Summary....66 Part 2—Design principles....67 3 Naming....69 3.1 Why do names matter?....70 3.2 What makes a name “good”?....70 3.2.1 Expressive....71 3.2.2 Simple....71 3.2.3 Predictable....72 3.3 Language, grammar, and syntax....72 3.3.1 Language....73 3.3.2 Grammar....73 3.3.3 Syntax....76 3.4 Context....77 3.5 Data types and units....77 3.6 Case study: What happens when you choose bad names?....79 3.7 Exercises....81 Summary....82 4 Resource scope and hierarchy....83 4.1 What is resource layout?....84 4.1.1 Types of relationships....85 4.1.2 Entity relationship diagrams....88 4.2 Choosing the right relationship....90 4.2.1 Do you need a relationship at all?....90 4.2.2 References or in-line data....91 4.2.3 Hierarchy....93 4.3 Anti-patterns....95 4.3.1 Resources for everything....95 4.3.2 Deep hierarchies....97 4.3.3 In-line everything....99 4.4 Exercises....100 Summary....100 5 Data types and defaults....101 5.1 Introduction to data types....102 5.1.1 Missing vs. null....103 5.2 Booleans....104 5.3 Numbers....105 5.3.1 Bounds....106 5.3.2 Default values....107 5.3.3 Serialization....107 5.4 Strings....109 5.4.1 Bounds....109 5.4.2 Default values....110 5.4.3 Serialization....111 5.5 Enumerations....112 5.6 Lists....113 5.6.1 Atomicity....113 5.6.2 Bounds....114 5.6.3 Default values....115 5.7 Maps....115 5.7.1 Bounds....118 5.7.2 Default values....118 5.8 Exercises....118 Summary....119 Part 3—Fundamentals....121 6 Resource identification....123 6.1 What is an identifier?....123 6.2 What makes a good identifier?....124 6.2.1 Easy to use....124 6.2.2 Unique....124 6.2.3 Permanent....125 6.2.4 Fast and easy to generate....125 6.2.5 Unpredictable....126 6.2.6 Readable, shareable, and verifiable....126 6.2.7 Informationally dense....127 6.3 What does a good identifier look like?....127 6.3.1 Data type....127 6.3.2 Character set....128 6.3.3 Identifier format....128 6.3.4 Checksums....129 6.3.5 Resource type....129 6.3.6 Hierarchy and uniqueness scope....130 6.4 Implementation....131 6.4.1 Size....131 6.4.2 Generation....132 6.4.3 Tomb-stoning....134 6.4.4 Checksum....134 6.4.5 Database storage....136 6.5 What about UUIDs?....137 6.6 Exercises....138 Summary....139 7 Standard methods....140 7.1 Motivation....141 7.2 Overview....141 7.3 Implementation....142 7.3.1 Which methods should be supported?....142 7.3.2 Idempotence and side effects....143 7.3.3 Get....144 7.3.4 List....145 7.3.5 Create....148 7.3.6 Update....150 7.3.7 Delete....151 7.3.8 Replace....152 7.3.9 Final API definition....154 7.4 Trade-offs....156 7.5 Exercises....156 Summary....157 8 Partial updates and retrievals....158 8.1 Motivation....159 8.1.1 Partial retrieval....159 8.1.2 Partial update....159 8.2 Overview....161 8.3 Implementation....164 8.3.1 Transport....164 8.3.2 Maps and nested interfaces....165 8.3.3 Repeated fields....168 8.3.4 Default values....169 8.3.5 Implicit field masks....171 8.3.6 Updating dynamic data structures....172 8.3.7 Invalid fields....173 8.3.8 Final API definition....174 8.4 Trade-offs....174 8.4.1 Universal support....175 8.4.2 Alternative implementations....175 8.5 Exercises....176 Summary....176 9 Custom methods....177 9.1 Motivation....178 9.1.1 Why not just standard methods?....178 9.2 Overview....181 9.3 Implementation....182 9.3.1 Side effects....183 9.3.2 Resources vs. collections....183 9.3.3 Stateless custom methods....185 9.3.4 Final API definition....187 9.4 Trade-offs....188 9.5 Exercises....188 Summary....189 10 Long-running operations....190 10.1 Motivation....191 10.2 Overview....192 10.3 Implementation....194 10.3.1 What does an LRO look like?....195 10.3.2 Resource hierarchy....196 10.3.3 Resolution....196 10.3.4 Error handling....200 10.3.5 Monitoring progress....201 10.3.6 Canceling operations....203 10.3.7 Pausing and resuming operations....204 10.3.8 Exploring operations....205 10.3.9 Persistence....206 10.3.10 Final API definition....208 10.4 Trade-offs....209 10.5 Exercises....210 Summary....210 11 Rerunnable jobs....211 11.1 Motivation....212 11.2 Overview....212 11.3 Implementation....214 11.3.1 Job resources....214 11.3.2 The custom run method....216 11.3.3 Job execution resources....217 11.3.4 Final API definition....220 11.4 Trade-offs....222 11.5 Exercises....222 Summary....222 Part 4—Resource relationships....223 12 Singleton sub-resources....225 12.1 Motivation....225 12.1.1 Why should we use a singleton sub-resource?....226 12.2 Overview....227 12.3 Implementation....228 12.3.1 Standard methods....228 12.3.2 Resetting....231 12.3.3 Hierarchy....231 12.3.4 Final API definition....232 12.4 Trade-offs....233 12.4.1 Atomicity....234 12.4.2 Exactly one sub-resource....234 12.5 Exercises....234 Summary....234 13 Cross references....236 13.1 Motivation....236 13.2 Overview....237 13.3 Implementation....238 13.3.1 Reference field name....238 13.3.2 Data integrity....239 13.3.3 Value vs. reference....240 13.3.4 Final API definition....242 13.4 Trade-offs....242 13.5 Exercises....242 Summary....242 14 Association resources....243 14.1 Motivation....243 14.2 Overview....244 14.2.1 Association alias methods....245 14.3 Implementation....246 14.3.1 Naming the association resource....246 14.3.2 Standard method behavior....246 14.3.3 Uniqueness....247 14.3.4 Read-only fields....247 14.3.5 Association alias methods....248 14.3.6 Referential integrity....249 14.3.7 Final API definition....250 14.4 Trade-offs....252 14.4.1 Complexity....252 14.4.2 Separation of associations....252 14.5 Exercises....252 Summary....253 15 Add and remove custom methods....254 15.1 Motivation....255 15.2 Overview....255 15.3 Implementation....256 15.3.1 Listing associated resources....256 15.3.2 Data integrity....257 15.3.3 Final API definition....258 15.4 Trade-offs....259 15.4.1 Nonreciprocal relationship....259 15.4.2 Relationship metadata....259 15.5 Exercises....260 Summary....260 16 Polymorphism....261 16.1 Motivation....261 16.2 Overview....262 16.3 Implementation....263 16.3.1 Deciding when to use polymorphic resources....263 16.3.2 Polymorphic structure....264 16.3.3 Polymorphic behavior....268 16.3.4 Why not polymorphic methods?....269 16.3.5 Final API definition....270 16.4 Trade-offs....271 16.5 Exercises....271 Summary....271 Part 5—Collective operations....273 17 Copy and move....275 17.1 Motivation....276 17.2 Overview....276 17.3 Implementation....277 17.3.1 Identifiers....277 17.3.2 Child resources....280 17.3.3 Related resources....281 17.3.4 External data....283 17.3.5 Inherited metadata....285 17.3.6 Atomicity....286 17.3.7 Final API definition....288 17.4 Trade-offs....288 17.5 Exercises....289 Summary....289 18 Batch operations....290 18.1 Motivation....291 18.2 Overview....291 18.3 Implementation....292 18.3.1 Atomicity....292 18.3.2 Operation on the collection....293 18.3.3 Ordering of results....294 18.3.4 Common fields....294 18.3.5 Operating across parents....295 18.3.6 Batch Get....297 18.3.7 Batch Delete....299 18.3.8 Batch Create....300 18.3.9 Batch Update....301 18.3.10 Final API definition....302 18.4 Trade-offs....305 18.5 Exercises....305 Summary....305 19 Criteria-based deletion....306 19.1 Motivation....307 19.2 Overview....307 19.3 Implementation....308 19.3.1 Filtering results....308 19.3.2 Validation only by default....310 19.3.3 Result count....311 19.3.4 Result sample set....311 19.3.5 Consistency....312 19.3.6 Final API definition....312 19.4 Trade-offs....313 19.5 Exercises....313 Summary....313 20 Anonymous writes....314 20.1 Motivation....314 20.2 Overview....315 20.3 Implementation....316 20.3.1 Consistency....317 20.3.2 Final API definition....319 20.4 Trade-offs....319 20.5 Exercises....320 Summary....320 21 Pagination....321 21.1 Motivation....322 21.2 Overview....322 21.3 Implementation....323 21.3.1 Page size....324 21.3.2 Page tokens....326 21.3.3 Total count....329 21.3.4 Paging inside resources....330 21.3.5 Final API definition....331 21.4 Trade-offs....332 21.4.1 Bi-directional paging....332 21.4.2 Arbitrary windows....332 21.5 Anti-pattern: Offsets and limits....332 21.6 Exercises....334 Summary....334 22 Filtering....335 22.1 Motivation....336 22.2 Overview....336 22.3 Implementation....337 22.3.1 Structure....338 22.3.2 Filter syntax and behavior....341 22.3.3 Final API definition....346 22.4 Trade-offs....347 22.5 Exercises....347 Summary....348 23 Importing and exporting....349 23.1 Motivation....350 23.2 Overview....351 23.3 Implementation....352 23.3.1 Import and export methods....353 23.3.2 Interacting with storage systems....354 23.3.3 Converting between resources and bytes....355 23.3.4 Consistency....357 23.3.5 Identifiers and collisions....358 23.3.6 Handling related resources....359 23.3.7 Failures and retries....360 23.3.8 Filtering and field masks....363 23.3.9 Final API definition....364 23.4 Trade-offs....366 23.5 Exercises....366 Summary....367 Part 6—Safety and security....369 24 Versioning and compatibility....371 24.1 Motivation....371 24.2 Overview....372 24.2.1 What is compatibility?....372 24.2.2 Defining backward compatibility....374 24.3 Implementation....380 24.3.1 Perpetual stability....381 24.3.2 Agile instability....382 24.3.3 Semantic versioning....385 24.4 Trade-offs....387 24.4.1 Granularity vs. simplicity....387 24.4.2 Stability vs. new functionality....388 24.4.3 Happiness vs. ubiquity....389 24.5 Exercises....391 Summary....391 25 Soft deletion....393 25.1 Motivation....394 25.2 Overview....394 25.3 Implementation....395 25.3.1 Deleted designation....395 25.3.2 Modifying standard methods....398 25.3.3 Undeleting....400 25.3.4 Expunging....401 25.3.5 Expiration....402 25.3.6 Referential integrity....403 25.3.7 Effects on other methods....403 25.3.8 Adding soft delete across versions....404 25.3.9 Final API definition....404 25.4 Trade-offs....405 25.5 Exercises....405 Summary....406 26 Request deduplication....407 26.1 Motivation....407 26.2 Overview....409 26.3 Implementation....409 26.3.1 Request identifier....409 26.3.2 Response caching....411 26.3.3 Consistency....412 26.3.4 Request ID collisions....414 26.3.5 Cache expiration....416 26.3.6 Final API definition....416 26.4 Trade-offs....418 26.5 Exercises....418 Summary....418 27 Request validation....419 27.1 Motivation....419 27.2 Overview....420 27.3 Implementation....421 27.3.1 External dependencies....423 27.3.2 Special side effects....424 27.3.3 Final API definition....424 27.4 Trade-offs....425 27.5 Exercises....425 Summary....425 28 Resource revisions....426 28.1 Motivation....427 28.2 Overview....427 28.3 Implementation....428 28.3.1 Revision identifiers....428 28.3.2 Creating revisions....430 28.3.3 Retrieving specific revisions....433 28.3.4 Listing revisions....434 28.3.5 Restoring a previous revision....435 28.3.6 Deleting revisions....436 28.3.7 Handling child resources....438 28.3.8 Final API definition....438 28.4 Trade-offs....439 28.5 Exercises....440 Summary....440 29 Request retrial....441 29.1 Motivation....441 29.2 Overview....442 29.2.1 Client-side retry timing....443 29.2.2 Server-specified retry timing....443 29.3 Implementation....444 29.3.1 Retry eligibility....444 29.3.2 Exponential back-off....446 29.3.3 Retry After....448 29.3.4 Final API definition....450 29.4 Trade-offs....450 29.5 Exercises....451 Summary....451 30 Request authentication....452 30.1 Motivation....453 30.1.1 Origin....453 30.1.2 Integrity....453 30.1.3 Nonrepudiation....454 30.2 Overview....454 30.3 Implementation....455 30.3.1 Credential generation....455 30.3.2 Registration and credential exchange....456 30.3.3 Generating and verifying raw signatures....457 30.3.4 Request fingerprinting....458 30.3.5 Including the signature....461 30.3.6 Authenticating requests....463 30.3.7 Final API definition....464 30.4 Trade-offs....465 30.5 Exercises....465 Summary....466 index....467 Numerics....467 A....467 B....468 C....468 D....470 E....471 F....471 G....472 H....472 I....472 J....473 K....473 L....473 M....473 N....474 O....474 P....474 R....475 S....477 T....478 U....478 V....478 W....479 Z....479