0%

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.

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