book

API Design Patterns

Name: API Design Patterns
Author: John J. Geewax
ISBN: 9781617295850

by John J. Geewax

July 2021

Intermediate to advanced

480 pages

14h 40m

English

Manning Publications

Audiobook available

Read now

Unlock full access

inside front cover
API Design Patterns
Copyright
dedication
contents
front matter
forewordprefaceacknowledgmentsabout this bookWho should read this bookHow this book is organized: A roadmapAbout the codeLive book discussion forumOther online resourcesabout the authorabout 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 Operational1.4.2 Expressive1.4.3 Simple1.4.4 PredictableSummary
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 pattern2.3.1 Name and synopsis2.3.2 Motivation2.3.3 Overview2.3.4 Implementation2.3.5 Trade-offs2.4 Case study: Twapi, a Twitter-like API2.4.1 Overview2.4.2 Listing messages2.4.3 Exporting dataSummary
Part 2 Design principles

3 Naming
3.1 Why do names matter?3.2 What makes a name “good”?3.2.1 Expressive3.2.2 Simple3.2.3 Predictable3.3 Language, grammar, and syntax3.3.1 Language3.3.2 Grammar3.3.3 Syntax3.4 Context3.5 Data types and units3.6 Case study: What happens when you choose bad names?3.7 ExercisesSummary
4 Resource scope and hierarchy
4.1 What is resource layout?4.1.1 Types of relationships4.1.2 Entity relationship diagrams4.2 Choosing the right relationship4.2.1 Do you need a relationship at all?4.2.2 References or in-line data4.2.3 Hierarchy4.3 Anti-patterns4.3.1 Resources for everything4.3.2 Deep hierarchies4.3.3 In-line everything4.4 ExercisesSummary
5 Data types and defaults
5.1 Introduction to data types5.1.1 Missing vs. null5.2 Booleans5.3 Numbers5.3.1 Bounds5.3.2 Default values5.3.3 Serialization5.4 Strings5.4.1 Bounds5.4.2 Default values5.4.3 Serialization5.5 Enumerations5.6 Lists5.6.1 Atomicity5.6.2 Bounds5.6.3 Default values5.7 Maps5.7.1 Bounds5.7.2 Default values5.8 ExercisesSummary
Part 3 Fundamentals
6 Resource identification
6.1 What is an identifier?6.2 What makes a good identifier?6.2.1 Easy to use6.2.2 Unique6.2.3 Permanent6.2.4 Fast and easy to generate6.2.5 Unpredictable6.2.6 Readable, shareable, and verifiable6.2.7 Informationally dense6.3 What does a good identifier look like?6.3.1 Data type6.3.2 Character set6.3.3 Identifier format6.3.4 Checksums6.3.5 Resource type6.3.6 Hierarchy and uniqueness scope6.4 Implementation6.4.1 Size6.4.2 Generation6.4.3 Tomb-stoning6.4.4 Checksum6.4.5 Database storage6.5 What about UUIDs?6.6 ExercisesSummary
7 Standard methods
7.1 Motivation7.2 Overview7.3 Implementation7.3.1 Which methods should be supported?7.3.2 Idempotence and side effects7.3.3 Get7.3.4 List7.3.5 Create7.3.6 Update7.3.7 Delete7.3.8 Replace7.3.9 Final API definition7.4 Trade-offs7.5 ExercisesSummary
8 Partial updates and retrievals
8.1 Motivation8.1.1 Partial retrieval8.1.2 Partial update8.2 Overview8.3 Implementation8.3.1 Transport8.3.2 Maps and nested interfaces8.3.3 Repeated fields8.3.4 Default values8.3.5 Implicit field masks8.3.6 Updating dynamic data structures8.3.7 Invalid fields8.3.8 Final API definition8.4 Trade-offs8.4.1 Universal support8.4.2 Alternative implementations8.5 ExercisesSummary
9 Custom methods
9.1 Motivation9.1.1 Why not just standard methods?9.2 Overview9.3 Implementation9.3.1 Side effects9.3.2 Resources vs. collections9.3.3 Stateless custom methods9.3.4 Final API definition9.4Trade-offs9.5 ExercisesSummary
10 Long-running operations
10.1 Motivation10.2 Overview10.3 Implementation10.3.1 What does an LRO look like?10.3.2 Resource hierarchy10.3.3 Resolution10.3.4 Error handling10.3.5 Monitoring progress10.3.6 Canceling operations10.3.7 Pausing and resuming operations10.3.8 Exploring operations10.3.9 Persistence10.3.10 Final API definition10.4 Trade-offs10.5 ExercisesSummary
11 Rerunnable jobs
11.1 Motivation11.2 Overview11.3 Implementation11.3.1 Job resources11.3.2 The custom run method11.3.3 Job execution resources11.3.4 Final API definition11.4 Trade-offs11.5 ExercisesSummary
Part 4 Resource relationships
12 Singleton sub-resources
12.1 Motivation12.1.1 Why should we use a singleton sub-resource?12.2 Overview12.3 Implementation12.3.1 Standard methods12.3.2 Resetting12.3.3 Hierarchy12.3.4 Final API definition12.4 Trade-offs12.4.1 Atomicity12.4.2 Exactly one sub-resource12.5 ExercisesSummary
13 Cross references
13.1 Motivation13.2 Overview13.3 Implementation13.3.1 Reference field name13.3.2 Data integrity13.3.3 Value vs. reference13.3.4 Final API definition13.4 Trade-offs11.5 ExercisesSummary
14 Association resources
14.1 Motivation14.2 Overview14.2.1 Association alias methods14.3 Implementation14.3.1 Naming the association resource14.3.2 Standard method behavior14.3.3 Uniqueness14.3.4 Read-only fields14.3.5 Association alias methods14.3.6 Referential integrity14.3.7 Final API definition14.4 Trade-offs14.4.1 Complexity14.4.2 Separation of associations14.5 ExercisesSummary
15 Add and remove custom methods
15.1 Motivation15.2 Overview15.3 Implementation15.3.1 Listing associated resources15.3.2 Data integrity15.3.3 Final API definition15.4 Trade-offs15.4.1 Nonreciprocal relationship15.4.2 Relationship metadata15.5 ExercisesSummary
16 Polymorphism
16.1 Motivation16.2 Overview16.3 Implementation16.3.1 Deciding when to use polymorphic resources16.3.2 Polymorphic structure16.3.3 Polymorphic behavior16.3.4 Why not polymorphic methods?16.3.5 Final API definition16.4 Trade-offs16.5 ExercisesSummary
Part 5 Collective operations
17 Copy and move
17.1 Motivation17.2 Overview17.3 Implementation17.3.1 Identifiers17.3.2 Child resources17.3.3 Related resources17.3.4 External data17.3.5 Inherited metadata17.3.6 Atomicity17.3.7 Final API definition17.4 Trade-offs17.5 ExercisesSummary
18 Batch operations
18.1 Motivation18.2 Overview18.3 Implementation18.3.1 Atomicity18.3.2 Operation on the collection18.3.3 Ordering of results18.3.4 Common fields18.3.5 Operating across parents18.3.6 Batch Get18.3.7 Batch Delete18.3.8 Batch Create18.3.9 Batch Update18.3.10 Final API definition18.4 Trade-offs18.5 ExercisesSummary
19 Criteria-based deletion
19.1 Motivation19.2 Overview19.3 Implementation19.3.1 Filtering results19.3.2 Validation only by default19.3.3 Result count19.3.4 Result sample set19.3.5 Consistency19.3.6 Final API definition19.4 Trade-offs19.5 ExercisesSummary
20 Anonymous writes
20.1 Motivation20.2 Overview20.3 Implementation20.3.1 Consistency20.3.2 Final API definition20.4 Trade-offs20.5 ExercisesSummary
21 Pagination
21.1 Motivation21.2 Overview21.3 Implementation21.3.1 Page size21.3.2 Page tokens21.3.3 Total count21.3.4 Paging inside resources21.3.5 Final API definition21.4 Trade-offs21.4.1 Bi-directional paging21.4.2 Arbitrary windows21.5 Anti-pattern: Offsets and limits21.6 ExercisesSummary
22 Filtering
22.1 Motivation22.2 Overview22.3 Implementation22.3.1 Structure22.3.2 Filter syntax and behavior22.3.3 Final API definition22.4 Trade-offs22.5 ExercisesSummary
23 Importing and exporting
23.1 Motivation23.2 Overview23.3 Implementation23.3.1 Import and export methods23.3.2 Interacting with storage systems23.3.3 Converting between resources and bytes23.3.4 Consistency23.3.5 Identifiers and collisions23.3.6 Handling related resources23.3.7 Failures and retries23.3.8 Filtering and field masks23.3.9 Final API definition23.4 Trade-offs23.5 ExercisesSummary
Part 6 Safety and security
24 Versioning and compatibility
24.1 Motivation24.2 Overview24.2.1 What is compatibility?24.2.2 Defining backward compatibility24.3 Implementation24.3.1 Perpetual stability24.3.2 Agile instability24.3.3 Semantic versioning24.4 Trade-offs24.4.1 Granularity vs. simplicity24.4.2 Stability vs. new functionality24.4.3 Happiness vs. ubiquity24.5 ExercisesSummary
25 Soft deletion
25.1 Motivation25.2 Overview25.3 Implementation25.3.1 Deleted designation25.3.2 Modifying standard methods25.3.3 Undeleting25.3.4 Expunging25.3.5 Expiration25.3.6 Referential integrity25.3.7 Effects on other methods25.3.8 Adding soft delete across versions25.3.9 Final API definition25.4 Trade-offs25.5 ExercisesSummary
26 Request deduplication
26.1 Motivation26.2 Overview26.3 Implementation26.3.1 Request identifier26.3.2 Response caching26.3.3 Consistency26.3.4 Request ID collisions26.3.5 Cache expiration26.3.6 Final API definition26.4 Trade-offs26.5 ExercisesSummary
27 Request validation
27.1 Motivation27.2 Overview27.3 Implementation27.3.1 External dependencies27.3.2 Special side effects27.3.3 Final API definition27.4 Trade-offs27.5 ExercisesSummary
28 Resource revisions
28.1 Motivation28.2 Overview28.3 Implementation28.3.1 Revision identifiers28.3.2 Creating revisions28.3.3 Retrieving specific revisions28.3.4 Listing revisions28.3.5 Restoring a previous revision28.3.6 Deleting revisions28.3.7 Handling child resources28.3.8 Final API definition28.4 Trade-offs28.5 ExercisesSummary
29 Request retrial
29.1 Motivation29.2 Overview29.2.1 Client-side retry timing29.2.2 Server-specified retry timing29.3 Implementation29.3.1 Retry eligibility29.3.2 Exponential back-off29.3.3 Retry After29.3.4 Final API definition29.4 Trade-offs29.5 ExercisesSummary
30 Request authentication
30.1 Motivation30.1.1 Origin30.1.2 Integrity30.1.3 Nonrepudiation30.2 Overview30.3 Implementation30.3.1 Credential generation30.3.2 Registration and credential exchange30.3.3 Generating and verifying raw signatures30.3.4 Request fingerprinting30.3.5 Including the signature30.3.6 Authenticating requests30.3.7 Final API definition30.4 Trade-offs30.5 ExercisesSummary
index

Content preview from API Design Patterns

Part 2 Design principles

Not all tools in our API design toolbox will be design patterns. In the next few chapters, we’ll look at some topics in API design that don’t quite qualify as design patterns (as defined in chapter 2), but are still important and helpful for guiding us on our journey toward building good APIs (as defined in chapter 1).

In chapter 3, we’ll look at guidelines for naming the different components of our APIs. Next, in chapter 4, we’ll cover how to logically arrange these components and define their relationships with one another. Finally, in chapter 5, we’ll look at how to decide between the many data types available for the different fields we might need in our APIs.

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Publisher Resources

ISBN: 9781617295850Publisher Support Publisher Website Errata Page

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

API Design Patterns

by John J. Geewax

Part 2 Design principles

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.