API Design Patterns

API Design Patterns

by John J. Geewax
Released July 2021
Publisher(s): Manning Publications
ISBN: 9781617295850

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

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.

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.

Quotes
A concept-rich book on API design patterns. Deeply engrossing and fun to read.
- Satej Sahu, Honeywell

Excellent companion for API design!
- Ruben Vandeginste, PeopleWare

The right way to build APIs.
- Jorge Ezequiel Bo, Naranjax

If API design or refactoring is in your future, this book is a great investment!
- Yul Williams, U.S. Department of Defense

Makes the complex puzzle of designing APIs into a delightful learning experience.
- Akshat Paul, McKinsey & Company

Publisher resources

View/Submit Errata

Table of contents

  1. inside front cover
  2. API Design Patterns
  3. Copyright
  4. dedication
  5. contents
  6. front matter
    1. foreword
    2. preface
    3. acknowledgments
    4. about this book
      1. Who should read this book
      2. How this book is organized: A roadmap
      3. About the code
      4. Live book discussion forum
      5. Other online resources
    5. about the author
    6. about the cover illustration
  7. Part 1 Introduction
  8. 1 Introduction to APIs
    1. 1.1 What are web APIs?
    2. 1.2 Why do APIs matter?
    3. 1.3 What are resource-oriented APIs?
    4. 1.4 What makes an API “good”?
      1. 1.4.1 Operational
      2. 1.4.2 Expressive
      3. 1.4.3 Simple
      4. 1.4.4 Predictable
    5. Summary
  9. 2 Introduction to API design patterns
    1. 2.1 What are API design patterns?
    2. 2.2 Why are API design patterns important?
    3. 2.3 Anatomy of an API design pattern
      1. 2.3.1 Name and synopsis
      2. 2.3.2 Motivation
      3. 2.3.3 Overview
      4. 2.3.4 Implementation
      5. 2.3.5 Trade-offs
    4. 2.4 Case study: Twapi, a Twitter-like API
      1. 2.4.1 Overview
      2. 2.4.2 Listing messages
      3. 2.4.3 Exporting data
    5. Summary
  10. Part 2 Design principles
  11. 3 Naming
    1. 3.1 Why do names matter?
    2. 3.2 What makes a name “good”?
      1. 3.2.1 Expressive
      2. 3.2.2 Simple
      3. 3.2.3 Predictable
    3. 3.3 Language, grammar, and syntax
      1. 3.3.1 Language
      2. 3.3.2 Grammar
      3. 3.3.3 Syntax
    4. 3.4 Context
    5. 3.5 Data types and units
      1. 3.6 Case study: What happens when you choose bad names?
    6. 3.7 Exercises
    7. Summary
  12. 4 Resource scope and hierarchy
    1. 4.1 What is resource layout?
      1. 4.1.1 Types of relationships
      2. 4.1.2 Entity relationship diagrams
    2. 4.2 Choosing the right relationship
      1. 4.2.1 Do you need a relationship at all?
      2. 4.2.2 References or in-line data
      3. 4.2.3 Hierarchy
    3. 4.3 Anti-patterns
      1. 4.3.1 Resources for everything
      2. 4.3.2 Deep hierarchies
      3. 4.3.3 In-line everything
    4. 4.4 Exercises
    5. Summary
  13. 5 Data types and defaults
    1. 5.1 Introduction to data types
      1. 5.1.1 Missing vs. null
    2. 5.2 Booleans
    3. 5.3 Numbers
      1. 5.3.1 Bounds
      2. 5.3.2 Default values
      3. 5.3.3 Serialization
    4. 5.4 Strings
      1. 5.4.1 Bounds
      2. 5.4.2 Default values
      3. 5.4.3 Serialization
    5. 5.5 Enumerations
    6. 5.6 Lists
      1. 5.6.1 Atomicity
      2. 5.6.2 Bounds
      3. 5.6.3 Default values
    7. 5.7 Maps
      1. 5.7.1 Bounds
      2. 5.7.2 Default values
    8. 5.8 Exercises
    9. Summary
  14. Part 3 Fundamentals
  15. 6 Resource identification
    1. 6.1 What is an identifier?
    2. 6.2 What makes a good identifier?
      1. 6.2.1 Easy to use
      2. 6.2.2 Unique
      3. 6.2.3 Permanent
      4. 6.2.4 Fast and easy to generate
      5. 6.2.5 Unpredictable
      6. 6.2.6 Readable, shareable, and verifiable
      7. 6.2.7 Informationally dense
    3. 6.3 What does a good identifier look like?
      1. 6.3.1 Data type
      2. 6.3.2 Character set
      3. 6.3.3 Identifier format
      4. 6.3.4 Checksums
      5. 6.3.5 Resource type
      6. 6.3.6 Hierarchy and uniqueness scope
    4. 6.4 Implementation
      1. 6.4.1 Size
      2. 6.4.2 Generation
      3. 6.4.3 Tomb-stoning
      4. 6.4.4 Checksum
      5. 6.4.5 Database storage
    5. 6.5 What about UUIDs?
    6. 6.6 Exercises
    7. Summary
  16. 7 Standard methods
    1. 7.1 Motivation
    2. 7.2 Overview
    3. 7.3 Implementation
      1. 7.3.1 Which methods should be supported?
      2. 7.3.2 Idempotence and side effects
      3. 7.3.3 Get
      4. 7.3.4 List
      5. 7.3.5 Create
      6. 7.3.6 Update
      7. 7.3.7 Delete
      8. 7.3.8 Replace
      9. 7.3.9 Final API definition
    4. 7.4 Trade-offs
    5. 7.5 Exercises
    6. Summary
  17. 8 Partial updates and retrievals
    1. 8.1 Motivation
      1. 8.1.1 Partial retrieval
      2. 8.1.2 Partial update
    2. 8.2 Overview
    3. 8.3 Implementation
      1. 8.3.1 Transport
      2. 8.3.2 Maps and nested interfaces
      3. 8.3.3 Repeated fields
      4. 8.3.4 Default values
      5. 8.3.5 Implicit field masks
      6. 8.3.6 Updating dynamic data structures
      7. 8.3.7 Invalid fields
      8. 8.3.8 Final API definition
    4. 8.4 Trade-offs
      1. 8.4.1 Universal support
      2. 8.4.2 Alternative implementations
    5. 8.5 Exercises
    6. Summary
  18. 9 Custom methods
    1. 9.1 Motivation
      1. 9.1.1 Why not just standard methods?
    2. 9.2 Overview
    3. 9.3 Implementation
      1. 9.3.1 Side effects
      2. 9.3.2 Resources vs. collections
      3. 9.3.3 Stateless custom methods
      4. 9.3.4 Final API definition
    4. 9.4Trade-offs
    5. 9.5 Exercises
    6. Summary
  19. 10 Long-running operations
    1. 10.1 Motivation
    2. 10.2 Overview
    3. 10.3 Implementation
      1. 10.3.1 What does an LRO look like?
      2. 10.3.2 Resource hierarchy
      3. 10.3.3 Resolution
      4. 10.3.4 Error handling
      5. 10.3.5 Monitoring progress
      6. 10.3.6 Canceling operations
      7. 10.3.7 Pausing and resuming operations
      8. 10.3.8 Exploring operations
      9. 10.3.9 Persistence
      10. 10.3.10 Final API definition
    4. 10.4 Trade-offs
    5. 10.5 Exercises
    6. Summary
  20. 11 Rerunnable jobs
    1. 11.1 Motivation
    2. 11.2 Overview
    3. 11.3 Implementation
      1. 11.3.1 Job resources
      2. 11.3.2 The custom run method
      3. 11.3.3 Job execution resources
      4. 11.3.4 Final API definition
    4. 11.4 Trade-offs
    5. 11.5 Exercises
    6. Summary
  21. Part 4 Resource relationships
  22. 12 Singleton sub-resources
    1. 12.1 Motivation
      1. 12.1.1 Why should we use a singleton sub-resource?
    2. 12.2 Overview
    3. 12.3 Implementation
      1. 12.3.1 Standard methods
      2. 12.3.2 Resetting
      3. 12.3.3 Hierarchy
      4. 12.3.4 Final API definition
    4. 12.4 Trade-offs
      1. 12.4.1 Atomicity
      2. 12.4.2 Exactly one sub-resource
    5. 12.5 Exercises
    6. Summary
  23. 13 Cross references
    1. 13.1 Motivation
    2. 13.2 Overview
    3. 13.3 Implementation
      1. 13.3.1 Reference field name
      2. 13.3.2 Data integrity
      3. 13.3.3 Value vs. reference
      4. 13.3.4 Final API definition
    4. 13.4 Trade-offs
    5. 11.5 Exercises
    6. Summary
  24. 14 Association resources
    1. 14.1 Motivation
    2. 14.2 Overview
      1. 14.2.1 Association alias methods
    3. 14.3 Implementation
      1. 14.3.1 Naming the association resource
      2. 14.3.2 Standard method behavior
      3. 14.3.3 Uniqueness
      4. 14.3.4 Read-only fields
      5. 14.3.5 Association alias methods
      6. 14.3.6 Referential integrity
      7. 14.3.7 Final API definition
    4. 14.4 Trade-offs
      1. 14.4.1 Complexity
      2. 14.4.2 Separation of associations
    5. 14.5 Exercises
    6. Summary
  25. 15 Add and remove custom methods
    1. 15.1 Motivation
    2. 15.2 Overview
    3. 15.3 Implementation
      1. 15.3.1 Listing associated resources
      2. 15.3.2 Data integrity
      3. 15.3.3 Final API definition
    4. 15.4 Trade-offs
      1. 15.4.1 Nonreciprocal relationship
      2. 15.4.2 Relationship metadata
    5. 15.5 Exercises
    6. Summary
  26. 16 Polymorphism
    1. 16.1 Motivation
    2. 16.2 Overview
    3. 16.3 Implementation
      1. 16.3.1 Deciding when to use polymorphic resources
      2. 16.3.2 Polymorphic structure
      3. 16.3.3 Polymorphic behavior
      4. 16.3.4 Why not polymorphic methods?
      5. 16.3.5 Final API definition
    4. 16.4 Trade-offs
    5. 16.5 Exercises
    6. Summary
  27. Part 5 Collective operations
  28. 17 Copy and move
    1. 17.1 Motivation
    2. 17.2 Overview
    3. 17.3 Implementation
      1. 17.3.1 Identifiers
      2. 17.3.2 Child resources
      3. 17.3.3 Related resources
      4. 17.3.4 External data
      5. 17.3.5 Inherited metadata
      6. 17.3.6 Atomicity
      7. 17.3.7 Final API definition
    4. 17.4 Trade-offs
    5. 17.5 Exercises
    6. Summary
  29. 18 Batch operations
    1. 18.1 Motivation
    2. 18.2 Overview
    3. 18.3 Implementation
      1. 18.3.1 Atomicity
      2. 18.3.2 Operation on the collection
      3. 18.3.3 Ordering of results
      4. 18.3.4 Common fields
      5. 18.3.5 Operating across parents
      6. 18.3.6 Batch Get
      7. 18.3.7 Batch Delete
      8. 18.3.8 Batch Create
      9. 18.3.9 Batch Update
      10. 18.3.10 Final API definition
    4. 18.4 Trade-offs
    5. 18.5 Exercises
    6. Summary
  30. 19 Criteria-based deletion
    1. 19.1 Motivation
    2. 19.2 Overview
    3. 19.3 Implementation
      1. 19.3.1 Filtering results
      2. 19.3.2 Validation only by default
      3. 19.3.3 Result count
      4. 19.3.4 Result sample set
      5. 19.3.5 Consistency
      6. 19.3.6 Final API definition
    4. 19.4 Trade-offs
    5. 19.5 Exercises
    6. Summary
  31. 20 Anonymous writes
    1. 20.1 Motivation
    2. 20.2 Overview
    3. 20.3 Implementation
      1. 20.3.1 Consistency
      2. 20.3.2 Final API definition
    4. 20.4 Trade-offs
    5. 20.5 Exercises
    6. Summary
  32. 21 Pagination
    1. 21.1 Motivation
    2. 21.2 Overview
    3. 21.3 Implementation
      1. 21.3.1 Page size
      2. 21.3.2 Page tokens
      3. 21.3.3 Total count
      4. 21.3.4 Paging inside resources
      5. 21.3.5 Final API definition
    4. 21.4 Trade-offs
      1. 21.4.1 Bi-directional paging
      2. 21.4.2 Arbitrary windows
    5. 21.5 Anti-pattern: Offsets and limits
    6. 21.6 Exercises
    7. Summary
  33. 22 Filtering
    1. 22.1 Motivation
    2. 22.2 Overview
    3. 22.3 Implementation
      1. 22.3.1 Structure
      2. 22.3.2 Filter syntax and behavior
      3. 22.3.3 Final API definition
    4. 22.4 Trade-offs
    5. 22.5 Exercises
    6. Summary
  34. 23 Importing and exporting
    1. 23.1 Motivation
    2. 23.2 Overview
    3. 23.3 Implementation
      1. 23.3.1 Import and export methods
      2. 23.3.2 Interacting with storage systems
      3. 23.3.3 Converting between resources and bytes
      4. 23.3.4 Consistency
      5. 23.3.5 Identifiers and collisions
      6. 23.3.6 Handling related resources
      7. 23.3.7 Failures and retries
      8. 23.3.8 Filtering and field masks
      9. 23.3.9 Final API definition
    4. 23.4 Trade-offs
    5. 23.5 Exercises
    6. Summary
  35. Part 6 Safety and security
  36. 24 Versioning and compatibility
    1. 24.1 Motivation
    2. 24.2 Overview
      1. 24.2.1 What is compatibility?
      2. 24.2.2 Defining backward compatibility
    3. 24.3 Implementation
      1. 24.3.1 Perpetual stability
      2. 24.3.2 Agile instability
      3. 24.3.3 Semantic versioning
    4. 24.4 Trade-offs
      1. 24.4.1 Granularity vs. simplicity
      2. 24.4.2 Stability vs. new functionality
      3. 24.4.3 Happiness vs. ubiquity
    5. 24.5 Exercises
    6. Summary
  37. 25 Soft deletion
    1. 25.1 Motivation
    2. 25.2 Overview
    3. 25.3 Implementation
      1. 25.3.1 Deleted designation
      2. 25.3.2 Modifying standard methods
      3. 25.3.3 Undeleting
      4. 25.3.4 Expunging
      5. 25.3.5 Expiration
      6. 25.3.6 Referential integrity
      7. 25.3.7 Effects on other methods
      8. 25.3.8 Adding soft delete across versions
      9. 25.3.9 Final API definition
    4. 25.4 Trade-offs
    5. 25.5 Exercises
    6. Summary
  38. 26 Request deduplication
    1. 26.1 Motivation
    2. 26.2 Overview
    3. 26.3 Implementation
      1. 26.3.1 Request identifier
      2. 26.3.2 Response caching
      3. 26.3.3 Consistency
      4. 26.3.4 Request ID collisions
      5. 26.3.5 Cache expiration
      6. 26.3.6 Final API definition
    4. 26.4 Trade-offs
    5. 26.5 Exercises
    6. Summary
  39. 27 Request validation
    1. 27.1 Motivation
    2. 27.2 Overview
    3. 27.3 Implementation
      1. 27.3.1 External dependencies
      2. 27.3.2 Special side effects
      3. 27.3.3 Final API definition
    4. 27.4 Trade-offs
    5. 27.5 Exercises
    6. Summary
  40. 28 Resource revisions
    1. 28.1 Motivation
    2. 28.2 Overview
    3. 28.3 Implementation
      1. 28.3.1 Revision identifiers
      2. 28.3.2 Creating revisions
      3. 28.3.3 Retrieving specific revisions
      4. 28.3.4 Listing revisions
      5. 28.3.5 Restoring a previous revision
      6. 28.3.6 Deleting revisions
      7. 28.3.7 Handling child resources
      8. 28.3.8 Final API definition
    4. 28.4 Trade-offs
    5. 28.5 Exercises
    6. Summary
  41. 29 Request retrial
    1. 29.1 Motivation
    2. 29.2 Overview
      1. 29.2.1 Client-side retry timing
      2. 29.2.2 Server-specified retry timing
    3. 29.3 Implementation
      1. 29.3.1 Retry eligibility
      2. 29.3.2 Exponential back-off
      3. 29.3.3 Retry After
      4. 29.3.4 Final API definition
    4. 29.4 Trade-offs
    5. 29.5 Exercises
    6. Summary
  42. 30 Request authentication
    1. 30.1 Motivation
      1. 30.1.1 Origin
      2. 30.1.2 Integrity
      3. 30.1.3 Nonrepudiation
    2. 30.2 Overview
    3. 30.3 Implementation
      1. 30.3.1 Credential generation
      2. 30.3.2 Registration and credential exchange
      3. 30.3.3 Generating and verifying raw signatures
      4. 30.3.4 Request fingerprinting
      5. 30.3.5 Including the signature
      6. 30.3.6 Authenticating requests
      7. 30.3.7 Final API definition
    4. 30.4 Trade-offs
    5. 30.5 Exercises
    6. Summary
  43. index

Product information

  • Title: API Design Patterns
  • Author(s): John J. Geewax
  • Release date: July 2021
  • Publisher(s): Manning Publications
  • ISBN: 9781617295850