
API Design Patterns
Description
Alles über E-Books | Antworten auf Fragen rund um E-Books, Kopierschutz und Dateiformate finden Sie in unserem Info- & Hilfebereich.
API Design Patterns lays out a set of design principles for building internal and public-facing 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 specific needs. Hands-on examples and relevant cases illustrate patterns for API fundamentals, advanced functionalities, and uncommon scenarios.
Foreword by Jon Skeet.
Purchase of the print book includes a free eBook in PDF, Kindle, and ePub formats from Manning Publications.
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. 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 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.
Table of Contents
PART 1 INTRODUCTION
1 Introduction to APIs
2 Introduction to API design patterns
PART 2 DESIGN PRINCIPLES
3 Naming
4 Resource scope and hierarchy
5 Data types and defaults
PART 3 FUNDAMENTALS
6 Resource identification
7 Standard methods
8 Partial updates and retrievals
9 Custom methods
10 Long-running operations
11 Rerunnable jobs
PART 4 RESOURCE RELATIONSHIPS
12 Singleton sub-resources
13 Cross references
14 Association resources
15 Add and remove custom methods
16 Polymorphism
PART 5 COLLECTIVE OPERATIONS
17 Copy and move
18 Batch operations
19 Criteria-based deletion
20 Anonymous writes
21 Pagination
22 Filtering
23 Importing and exporting
PART 6 SAFETY AND SECURITY
24 Versioning and compatibility
25 Soft deletion
26 Request deduplication
27 Request validation
28 Resource revisions
29 Request retrial
30 Request authentication
More details
Other editions
Additional editions

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