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

API Design Patterns lays out a set of design principles for building internal and public-facing APIs.

Summary

A collection of best practices and design standards for web and internal 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 your specific needs. Hands-on examples and relevant use-cases illustrate patterns for API fundamentals, advanced functionalities, and even uncommon scenarios.

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 to use. 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 design 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.