API Design Patterns PDF

J.J. Geewax
 API Design Patterns
Mastering API Design for Reliability and Usability
Written by Bookey
Check more about API Design Patterns Summary
Listen API Design Patterns Audiobook
About the book
API Design Patterns offers a comprehensive exploration of
best practices and design standards for creating robust and
user-friendly APIs in today's complex software ecosystems.
Aimed at developers, this invaluable resource presents a
detailed catalog that emphasizes stability, reliability, and ease
of use. Richly illustrated with examples and real-world use
cases, the book covers fundamental patterns, intricate system
designs, and addresses less common scenarios and edge cases,
equipping you with the knowledge to craft APIs that
effectively meet the needs of both users and fellow developers.
About the author
J.J. Geewax is a seasoned software architect and technology
consultant with extensive experience in designing and
implementing robust API solutions across various industries.
With a passion for enhancing developer productivity and
system interoperability, Geewax leverages his deep
understanding of application architecture to craft innovative
design patterns that cater to the evolving needs of modern
software development. As a thought leader in the field, he
frequently shares his insights through writing, speaking
engagements, and hands-on workshops, making complex
concepts accessible to both seasoned professionals and
newcomers alike. His book, "API Design Patterns," reflects his
commitment to equipping developers with the tools and
knowledge necessary to create scalable and maintainable APIs.
Summary Content List
Chapter 1 : API Design Patterns

Chapter 2 : 1 Introduction to APIs

Chapter 3 : 2 Introduction to API design patterns

Chapter 4 : 3 Naming

Chapter 5 : 4 Resource scope and hierarchy

Chapter 6 : 5 Data types and defaults

Chapter 7 : 6 Resource identification

Chapter 8 : 7 Standard methods

Chapter 9 : 8 Partial updates and retrievals

Chapter 10 : 9 Custom methods

Chapter 11 : 10 Long-running operations

Chapter 12 : 11 Rerunnable jobs

Chapter 13 : 12 Singleton sub-resources

Chapter 14 : 13 Cross references

Chapter 15 : 14 Association resources

Chapter 16 : 15 Add and remove custom methods

Chapter 17 : 16 Polymorphism

Chapter 18 : 17 Copy and move

Chapter 19 : 18 Batch operations

Chapter 20 : 19 Criteria-based deletion

Chapter 21 : 20 Anonymous writes

Chapter 22 : 21 Pagination

Chapter 23 : 22 Filtering

Chapter 24 : 23 Importing and exporting

Chapter 25 : 24 Versioning and compatibility

Chapter 26 : 25 Soft deletion

Chapter 27 : 26 Request deduplication

Chapter 28 : 27 Request validation

Chapter 29 : 28 Resource revisions

Chapter 30 : 29 Request retrial

Chapter 31 : 30 Request authentication

Chapter 1 Summary : API Design
Patterns

Foreword

Jon Skeet shares his journey from drumming to

understanding web APIs during the COVID-19 pandemic. He
emphasizes the blend of frustration and empowerment
experienced when navigating various protocols and API
designs. Skeet posits that while the book can't change API
experiences alone, it can guide developers toward a more
consistent, efficient approach. The overarching message is
the value of well-designed APIs, which often go unnoticed,
but significantly enhance user experience and reduce
frustration.
Preface

The author reflects on the disparity between theoretical

computer science learned in school and the practical,
design-oriented challenges faced in real-world applications.
He highlights the importance of design in creating
user-friendly web APIs and introduces the book as a
compendium of insights gathered over years, offering
battle-tested guidelines for API design. The goal is to
facilitate a fruitful dialogue on API design, paving the way
for future discussions and advancements in the field.

About This Book

API Design Patterns provides a comprehensive guide to

reusable patterns for building web APIs, starting with
foundational design principles and progressing to specific
patterns for various API scenarios.

Who Should Read This Book

This book is aimed at anyone involved in building or

planning to build web APIs, especially those exposed to
public users. Familiarity with serialization formats and HTTP
methods is beneficial but not essential.

How This Book Is Organized: A Roadmap

The book is structured into six parts:

1.
General API Design Principles
: Discusses fundamental concepts, naming conventions,
resource relationships, and data types.
2.
Design Patterns
: Catalogs common patterns applicable to various APIs,
addressing identifiers, standard methods, long-running
operations, and resource relationships.
3.
Collections and Groups
: Focuses on batch operations, filtering, and pagination for
managing multiple resources.
4.
Safety and Security
: Covers versioning, user protection, identification of
requests, and security practices.
5.
Examples and Code
: Source code is presented in TypeScript to illustrate design
concepts, showing both schemas and API methods.

Live Book Discussion Forum

Manning Publications offers a platform for readers to discuss

the book, pose questions, and engage with the author and
other readers.

Other Online Resources

Readers are encouraged to explore additional materials on

API design topics through [[Link]]([Link]

About the Author

J.J. Geewax is a software engineer at Google with a focus on

API design and real-time payment systems. His contributions
extend to various resources and collaborations aimed at
improving API design standards.

About the Cover Illustration

The book cover features a historical illustration titled
"Merchant of Prints in Vienna," reflecting cultural diversity
and the richness of regional life, symbolizing the creativity
and variety in the tech space today.
 Chapter 2 Summary : 1 Introduction to
APIs

Section Content

1. Introduction to APIs In-depth exploration of APIs, covering interfaces, definitions, resource orientation, and quality
criteria.

1.1 What are Web APIs? Facilitate remote interaction between systems, differing from local libraries in lack of user control
over changes impacting functionality.

1.2 Why do APIs Matter? They bridge human-focused software and automation, providing a stable communication method
for system composition.

1.3 What are Focus on managing resources with a standard set of methods for consistency, making systems
Resource-Oriented APIs? comprehensible and maintainable.

1.4 What Makes an API Must fulfill desired functionality and meet qualities of operational, expressive, simple, and
“Good”? predictable.

1.4.1 Operational Effectively performs intended functionality.

1.4.2 Expressive Provides a clear interface for users without convoluted workarounds.

1.4.3 Simple Exposes functionalities straightforwardly, keeping common use cases uncomplicated.

1.4.4 Predictable Consistency in naming and behavior reduces the learning curve for users.

Summary Highlights resource orientation and the need for predictable, user-friendly interfaces, setting the
stage for further exploration of design patterns.

1. Introduction to APIs
This chapter offers an in-depth exploration of APIs, covering
key concepts such as interfaces, the definition of APIs,
resource orientation, and criteria for determining the quality
of an API.

1.1 What are Web APIs?

Web APIs facilitate interaction between computer systems,

designed for remote usage. They differ from local libraries in
that users cannot control the API’s changes, which can
impact functionality directly.

1.2 Why do APIs Matter?

APIs bridge the gap between human-focused software and

automation. They provide a stable way for machines to
communicate, facilitating composition by allowing different
software components to work together in new ways.

1.3 What are Resource-Oriented APIs?

Resource-oriented APIs emphasize managing “resources”

rather than individual actions. They utilize a standard set of
methods for consistency and are particularly advantageous
for building comprehensible and maintainable systems.

1.4 What Makes an API “Good”?

To classify an API as "good," it must fulfill two key criteria:

- It provides desired functionality that users can interact with
programmatically.
- It meets several desirable qualities:

1.4.1 Operational

The API must perform its intended functionality effectively.

1.4.2 Expressive

The API should offer a clear and straightforward interface

for users to utilize its functionalities without convoluted
workarounds.

1.4.3 Simple

The API should expose functionalities straightforwardly,

keeping common use cases uncomplicated while allowing for
more complex interactions.

1.4.4 Predictable

Consistency in naming and behavior across the API helps

reduce the learning curve, making it easier for users to
understand and utilize the API effectively.

Summary

The chapter articulates important aspects of API design,

highlighting resource orientation and the significance of
creating predictable, user-friendly interfaces. It lays the
groundwork for deeper exploration into specific design
patterns in subsequent chapters.
Example
Key Point:The importance of resource-oriented APIs
for clarity and maintainability.
Example:Imagine you’re developing a mobile
application that fetches user data. Instead of crafting
specific API calls for every action like 'getUser' or
'updateProfile', you utilize a resource-oriented API
model. This API allows you to treat user data as a
resource, providing standard methods like GET, POST,
PUT, and DELETE. This approach not only makes your
code cleaner and easier to manage but also helps your
team (and future developers) instantly grasp the system's
functionality without navigating through a tangle of
disparate actions.
Critical Thinking
Key Point:Assessing API Quality
Critical Interpretation:The chapter emphasizes criteria
for a 'good' API, focusing on functionality and user
experience. This perspective suggests a standardized
approach to API design. However, one must question
whether these criteria alone capture the complexities of
real-world applications. While a predictable and simple
interface is beneficial, it may overlook aspects such as
flexibility and evolving use cases, as noted by
researchers like Micheal Stal in 'Designing RESTful
Web APIs,' where user context plays a critical role.
 Chapter 3 Summary : 2 Introduction to
API design patterns
Section Summary

Introduction to API Design Discusses the significance and structural elements of API design patterns.
Patterns

What are API Design Established solutions for common API development problems, serving as reusable blueprints.
Patterns?

Why are API Design Provide a structured approach to mitigate risks in API design, aiding iterative development.
Patterns Important?

Anatomy of an API Design Includes components like naming conventions, motivation, applications, implementations, and
Pattern trade-offs.

Case Study: Twapi, a A practical example demonstrating the necessity of design patterns in API tasks such as
Twitter-like API message listing.

Summary API design patterns simplify modifications and enhance robustness; exploring identification,
motivation, implementation, and trade-offs.

Introduction to API Design Patterns

This chapter discusses the significance of API design

patterns, their anatomy, and the structural elements that
constitute an API design pattern.

What are API Design Patterns?

API design patterns are established solutions to common

problems in API development. They serve as blueprints that
can be reused across various situations with minor
adjustments. This section emphasizes the role of patterns as
guiding frameworks rather than specific implementations.

Why are API Design Patterns Important?

API design patterns are critical because APIs are often rigid,
making iterative design more complex. These patterns
provide a structured approach that mitigates risks and
complexities inherent in API design by leveraging proven
solutions that ease future modifications.

Anatomy of an API Design Pattern

API design patterns consist of several components that

collectively address different aspects of usage and
implementation. Important components include naming
conventions, motivation behind the pattern, an overview of
its application, implementations, and trade-offs of adopting
the pattern.

Case Study: Twapi, a Twitter-like API

Install Bookey App to Unlock Full Text and
Audio
The chapter includes a practical case study focusing on
Twapi—a hypothetical API similar to Twitter. It
Chapter 4 Summary : 3 Naming

Chapter 4: Naming

This chapter emphasizes the importance of naming in

software engineering, particularly in API design. It highlights
the significance of choosing clear and concise names that
will endure over time, as names are integral to user
interaction with an API.

3.1 Why do names matter?

Names are essential in software engineering since they are

the primary means of communication regarding what various
components do. Unlike compiled code, where names may be
hidden post-compilation, API names remain visible to users.
Changing names in APIs can lead to confusion and
complications, similar to changing one’s phone number
without notifying everyone.

3.2 What makes a name "good"?

Good names tend to be operational, expressive, simple, and

predictable:
*
3.2.1 Expressive:
Names should clearly convey what they represent, reducing
ambiguity. Context matters, as using a generic term like
"topic" could lead to confusion if it has multiple meanings.
*
3.2.2 Simple:
While names need to be expressive, they should avoid
unnecessary complexity. A balance must be struck between
expressiveness and simplicity.
*
3.2.3 Predictable:
Consistency in naming helps users learn and predict the
meaning of names quickly, enhancing their experience.

3.3 Language, grammar, and syntax

Understanding language nuances is vital in naming.

American English is preferred for maximum interoperability.
Key considerations include:
*
3.3.1 Language:
Use American English to foster consistency.
*
3.3.2 Grammar:
Follow structured naming conventions, like using imperative
mood for action-related RPCs.
*
3.3.3 Syntax:
Choose a consistent case for names (e.g., camelCase,
snake_case), and avoid using reserved keywords.

3.4 Context

The context in which names are used greatly affects their

meanings. This means a name like "book" can vary in
interpretation based on the API’s domain. Names should be
pertinent to their context to avoid misunderstandings.

3.5 Data types and units

Units are crucial for clarity in field names. Including data

types or units in names (like “sizeBytes” instead of just
“size”) eliminates confusion and helps convey meaning
effectively. Utilizing richer data types can also clarify the
intention behind a name.
3.6 Case study: What happens when you choose bad
names?

Illustrative examples highlight risks associated with bad

naming choices:
*
Subtle meaning:
Misleading names can create confusion similar to ordering
ten donuts but receiving less.
*
Units:
Critical issues can arise from confusing units, as
demonstrated by NASA's Mars Climate Orbiter incident,
leading to mission failure.

3.7 Exercises

This section invites reflection and discussion on cases of

naming practices in API design.

Summary

Effective naming is critical in API design, requiring

simplicity, expressiveness, and predictability. Names should
be consistent with language rules and crafted thoughtfully to
clarify their functions and avoid unforeseen complications in
usability and context interpretation.
Example
Key Point:The Essence of Naming in API Design
Example:When designing an API, imagine you're
creating a door to a new world; the name you choose for
each endpoint is the key that unlocks understanding for
your users. For instance, if you label a function
'submitQuiz', users immediately grasp its purpose,
reducing their need to second-guess what actions to
take. Conversely, if you called it 'processData',
confusion reigns, like navigating a maze blindfolded. By
prioritizing clarity and intuition in your naming
conventions, you not only enhance usability but
empower users to interact effortlessly with your API,
ensuring they find their way with confidence and ease.
 Chapter 5 Summary : 4 Resource scope
and hierarchy
Section Content

Chapter Title Resource Scope and Hierarchy

Key Topics

What a resource layout is

Various types of resource relationships
Entity relationship diagrams description
Choosing the right relationship
Resource layout anti-patterns

4.1 What is Resource Arrangement of resources in an API, highlighting fields and relationships, similar to
Layout? entity-relationship models in relational databases.

4.1.1 Types of
Relationships
Reference Relationships
Many-to-Many Relationships
Self-reference Relationships
Hierarchical Relationships

4.1.2 Entity Relationship Visual representations of resource relationships and cardinality to illustrate interactions.
Diagrams

4.2 Choosing the Right Evaluate the necessity, type, and impact of relationships based on functionality and long-term
Relationship costs.

4.3 Anti-patterns

Resources for Everything

Deep Hierarchies
In-line Everything

4.4 Exercises Engage with personal examples of resource relationships and diagram interaction types.

Summary Resource layout involves meaningful connections and simplified structures for efficient API
design.

4. Resource Scope and Hierarchy

This chapter covers:
- What a resource layout is
- Various types of resource relationships (reference,
many-to-many, etc.)
- How entity relationship diagrams describe resource layout
- Choosing the right relationship between resources
- Resource layout anti-patterns to avoid

4.1 What is Resource Layout?

Resource layout refers to the arrangement of resources within

an API, including the fields that define those resources and
their relationships. It is akin to the entity-relationship model
in a relational database, illustrating how resources like
`ChatRoom` and `User` relate to each other. Understanding
resource layout helps in visualizing the interactions between
different resources.

4.1.1 Types of Relationships

When establishing resource layout, it’s crucial to consider

how resources relate to each other. Key relationship types
include:
-
Reference Relationships
: Basic connections where one resource points to another,
e.g., a `Message` referencing a `User`.

-
Many-to-Many Relationships
: Scenarios where multiple resources point to multiple
instances of each other, such as users belonging to multiple
chat rooms.

-
Self-reference Relationships
: Resources that refer to themselves, often found in
hierarchical data structures, like employees referencing
reports.

-
Hierarchical Relationships
: These suggest ownership or containment, like a folder
containing files, where deleting a parent resource deletes
child resources.

4.1.2 Entity Relationship Diagrams

Diagrams that visually represent resource relationships and
cardinality (the number of instances that can exist in a
relationship) provide clarity on how resources interact.

4.2 Choosing the Right Relationship

Determining whether a relationship is necessary and what

type of relationship to implement is critical. Relationships
should be based on functionality that enhances API behavior,
acknowledging potential performance impacts.
-
Do You Need a Relationship at All?
: Understand the long-term costs associated with maintaining
relationships between resources.
-
References or In-line Data
: Decide whether to duplicate related data (in-line) or
reference it, weighing factors like data retrieval efficiency
and the frequency of access.
-
Hierarchy
: Analyze when hierarchical relationships are appropriate,
benefiting from inheritance of behaviors between parent and
child resources but also being cautious about the limitations
of a single-parent structure.

4.3 Anti-patterns

Common drawbacks include:

-
Resources for Everything
: Avoid creating a resource for every minor concept; focus on
significant entities that require independent interaction.
-
Deep Hierarchies
: Overly complex hierarchies can confuse users and
complicate data management. Opt for flatter structures unless
hierarchical behavior is necessary.
-
In-line Everything
: Beware of de-normalizing all data, which can lead to data
integrity problems and make updates complicated.

4.4 Exercises

Consider your own examples of resource relationships and

diagram various interaction types to reinforce learning.
Summary

Resource layout encompasses the relationships and

arrangements of resources in an API. Prioritize meaningful
connections, simplify complex structures, and be judicious in
the use of relationships to maintain an efficient and
comprehensible API design.
Example
Key Point:Visualize resource interconnections to
enhance API efficiency.
Example:Imagine you are developing an online chat
application. Consider how `User` and `ChatRoom`
resources relate: you must decide if each `User` can
belong to multiple `ChatRooms` or just one. By
thoughtfully establishing this many-to-many
relationship, you create a streamlined experience for
users to navigate between different chat rooms
seamlessly. When you map out these relationships using
entity relationship diagrams, you can see the structure
clearly, avoiding unnecessary complexity that could
confuse developers or hinder performance. Emphasizing
clear resource layout ensures that users enjoy a smooth
and logical interface.
Critical Thinking
Key Point:Resource layout is critical for API
effectiveness and user experience.
Critical Interpretation:While the author emphasizes the
importance of carefully considering resource
relationships and layouts to enhance API functionality
and performance, it is essential to recognize that this
perspective may not universally apply. The intricacies
of API design can vary greatly based on specific use
cases, and a blanket approach may overlook unique
requirements or lead to unnecessary complexity. Critics
might argue that the emphasis on avoiding deep
hierarchies and intricate relationships might lead to
oversimplification, potentially stripping away valuable
contextual connections between resources. For a
contrasting viewpoint, one could refer to 'REST API
Design Rulebook' by Mark Masse, which discusses
more elaborate use cases for deep hierarchies and
denormalized data strategies in certain contexts.
 Chapter 6 Summary : 5 Data types and
defaults
Section Content

Chapter 6: Data This chapter discusses the significance of data types in API design, focusing on null vs. missing
Types and Defaults values and serialization.

5.1 Introduction to Data types direct how programs manage data and interact through serialization protocols, which are
Data Types essential for cross-language compatibility.

5.1.1 Missing vs. Clarifies the distinction between missing data and null values in serialization, emphasizing the need
Null for clear API definitions.

5.2 Booleans Booleans are used for true/false flags; positive flags enhance clarity over negative flags which can
complicate understanding.

5.3 Numbers Numbers hold information but should not serve as identifiers. Proper numeric bounds and default
values ensure predictable behavior.

5.4 Strings Strings are common in APIs; attention should be given to boundary conditions, input management,
and UTF-8 encoding.

5.5 Enumerations While useful, enumerations limit flexibility; using string representations allows for clearer API design
and easier updates.

5.6 Lists Lists should be atomic, replacing the entire list upon modification, maintaining homogeneous types,
and having set size limits.

5.7 Maps Maps provide key-value pairs, distinct from custom types. Limiting keys, values, and their sizes is
vital for efficiency.

5.8 Exercises The chapter ends with exercises to reinforce understanding of the discussed data types.

Summary Knowledge of data types is essential for effective API design, focusing on handling null/missing
values, naming conventions, serialization, and setting boundaries.

Chapter 6: Data Types and Defaults

This chapter covers the importance of data types in API

design, including the differences between null values and
missing values, the various primitive and collective data
types, and how to handle serialization.

5.1 Introduction to Data Types

Data types tell programs how to handle data and interact with
operators. In API design, it is crucial to consider types that
allow interaction across various programming languages,
often relying on serialization protocols for structured data
representations.

5.1.1 Missing vs. Null

This section discusses the confusion between missing data

and null values in serialization formats. The API must clearly
define how to handle null and missing values to avoid
inconsistencies.

5.2 Booleans

Booleans represent true/false values used for storing flags.

When designing APIs with boolean fields, it is essential to
useInstall
positive Bookey Appfortoclarity,
Boolean flags Unlock Full Text
as negative flagsand
can
increase cognitive load. Audio
Chapter 7 Summary : 6 Resource
identification

Resource Identification Summary

Introduction to Resource Identifiers

This chapter delves into the concept of resource identifiers,

emphasizing their importance in APIs. It defines identifiers,
explores attributes of good identifiers, discusses common
formats like UUIDs, and offers guidance on creating
effective identifier systems.

What is an Identifier?

Identifiers serve as unique addresses for resources in an API,

enabling lookup operations within collections of resources.
They can vary in form, such as strings or integers, but not all
identifiers are equally effective. Examples like
government-issued identifiers illustrate the challenges in
ensuring uniqueness.
What Makes a Good Identifier?

1.
Easy to Use
: Identifiers should facilitate straightforward resource
lookups without confusion.
2.
Unique
: Must be distinct within a defined context; ambiguity leads
to potential identification issues.
3.
Permanent
: Identifiers should not change post-assignment, ensuring
consistent resource identification.
4.
Fast and Easy to Generate
: Creation of identifiers should be efficient to maintain
smooth API operations.
5.
Unpredictable
: Security requires that identifiers are hard to guess or
predict.
6.
Readable, Shareable, and Verifiable
: Human-friendly formats ease communication and
verification of identifiers.
7.
Informationally Dense
: Identifiers should pack significant information into brief
formats.

Characteristics of a Good Identifier Format

Good identifiers might be structured using a recommended

approach that includes strings, ASCII characters, and
serialization formats like Crockford's Base32. This approach
enhances readability and minimizes confusion.

Implementation Strategies

To implement effective identifiers:

- Choose a fixed size for identifiers to avoid database
complexity.
- Always generate identifiers in a controlled way to prevent
user-induced collisions.
- Utilize checksum values within identifiers to verify their
integrity and address potential mistakes.
UUID Considerations

While UUIDs offer a standardized format for identifiers, they

may be unnecessarily large or less readable compared to
custom schemes. The chapter suggests using UUIDs
internally while presenting Base32 identifiers externally for
better usability.

Exercises

- Design encoding with a larger checksum.

- Calculate collision probabilities for a specific identifier
size.
- Create an algorithm for collision avoidance in shorter
identifiers.

Conclusion

Effective identifiers in APIs are essential for resource

management. They should enhance usability while ensuring
uniqueness and integrity through thoughtful design choices,
balancing attributes like readability and information density
for optimal API performance.
Example
Key Point:Understanding and implementing effective
identifiers is crucial for seamless API interactions.
Example:Imagine you are developing an API for a
library management system. As a user searching for a
book, you input a unique identifier; however, if that
identifier is ambiguous or changes frequently, your
lookup turns into a frustrating guessing game. For
instance, when you enter ‘12345’, if it belongs to two
different copies of the same book, the system will
struggle to deliver the right one. Ensuring that your
identifiers are unique, readable, and stable means that
when you search for ‘12345’, you instantly retrieve the
intended copy of ‘The Great Gatsby’ without confusion.
This clarity fosters a respectful and efficient relationship
between users and the API.
 Chapter 8 Summary : 7 Standard
methods
Section Content

Chapter Title Standard Methods

Overview This chapter discusses standard methods in API design with a focus on predictability, outlining
methods like GET, LIST, CREATE, UPDATE, DELETE, and REPLACE, including their benefits and
drawbacks.

7.1 Motivation A well-designed API enables users to quickly understand and use familiar methods, enhancing
predictability and user satisfaction.

7.2 Overview of Details on standard methods:

Standard Methods
GET: Retrieves resources (e.g., GetChatRoom())
LIST: Lists resources (e.g., ListChatRooms())
CREATE: Creates resources (e.g., CreateMessage())
UPDATE: Modifies resources (e.g., UpdateUserProfile())
DELETE: Removes resources (e.g., DeleteChatRoom())
REPLACE: Replaces resources (e.g., ReplaceChatRoom())

7.3 Implementation Covers practical considerations for implementing methods based on resource characteristics, like
of Standard Methods immutability.

7.3.1 Supported Not all resources need to support every method; documentation is needed for unsupported methods.
Methods

7.3.2 Idempotence Avoid side effects for predictable outcomes; idempotence guarantees consistent results from repeated
and Side Effects requests.

7.3.3 to 7.3.8 Details on standard methods:

Standard Method
Descriptions GET: Idempotent with no side effects.
LIST: Avoids complexity with access control.
CREATE: Prefers server-generated identifiers.
UPDATE: Uses PATCH for partial modifications.
DELETE: Typically non-idempotent, fails if resource not found.
REPLACE: Uses PUT for clear overwrite actions.

7.4 Trade-offs Standard methods provide a clear structure, which may reduce flexibility but increases ease of
understanding for users.

7.5 Exercises Practices that reinforce the understanding of standard methods and their behaviors.

Summary Standard methods enhance consistency and predictability in API design, aligning with behavioral
principles, and enabling effective user interaction.
8. Standard Methods

Overview

This chapter discusses the importance of standard methods in

API design, particularly focusing on predictability.
Predictable APIs allow users to apply their existing
knowledge of standard actions across various resources,
making learning easier. The chapter outlines the standard
methods (GET, LIST, CREATE, UPDATE, DELETE) and a
semi-standard method (REPLACE), as well as their benefits
and drawbacks.

7.1 Motivation

A well-designed API allows users to leverage familiar

methods to understand and use the API quickly.
Standardizing methods across an API fosters predictability,
which contributes to user satisfaction. Inspired by REST
specifications, this section emphasizes the need for
guidelines that prevent ambiguity in method behaviors and
enhance consistency.
7.2 Overview of Standard Methods

The standard methods and their expected behaviors are

outlined:
-
GET
: Retrieves existing resources (e.g., GetChatRoom())
-
LIST
: Lists collections of resources (e.g., ListChatRooms())
-
CREATE
: Creates new resources (e.g., CreateMessage())
-
UPDATE
: Modifies existing resources (e.g., UpdateUserProfile())
-
DELETE
: Removes resources (e.g., DeleteChatRoom())
-
REPLACE
: Replaces entire resources (e.g., ReplaceChatRoom())
Clarity in method implementation is crucial to avoid
ambiguity in their interpretation.

7.3 Implementation of Standard Methods

This section covers practical considerations in implementing

standard methods, including deciding which methods to
support based on the resource characteristics, such as
immutability.

7.3.1 Which Methods Should Be Supported?

Not every resource must support all standard methods.

Resources that are immutable or permanent might not allow
updates or deletions. Documentation is necessary for cases
where certain methods are unsupported.

7.3.2 Idempotence and Side Effects

Standard methods should avoid side effects, as they can lead

to unpredictable outcomes (e.g., data loss). Idempotence
ensures that repeated requests yield the same outcome,
minimizing the risk of unintended consequences.

7.3.3 to 7.3.8 Standard Methods Descriptions

Each standard method is examined in detail:
-
GET
: Should retrieve data without side effects and be idempotent.
-
LIST
: Helps browse available resources but must handle access
control and avoid complexity by not including counts or
sorts.
-
CREATE
: Establishes new resources. Server-generated identifiers are
preferred, though consumers can request specific ones if
necessary.
-
UPDATE
: Uses the PATCH method to modify existing resources
without altering aspects that aren’t specified.
-
DELETE
: A simple method to remove resources, generally
non-idempotent, as attempting to delete a non-existing
resource should lead to failure.
-
REPLACE
: A semi-standard method to overwrite entire resources using
the PUT method, effectively creating or updating without
ambiguity about the resource's existence.

7.4 Trade-offs

Using standard methods involves trade-offs, such as reduced

flexibility for ease of understanding. However, this
identifiable structure benefits API users by leveraging their
prior knowledge.

7.5 Exercises

Practices that challenge understanding of standard methods

and their specific behaviors.

Summary

Standard methods drive consistency and predictability in API

design. These methods should adhere to specific behavioral
principles, be idempotent, and avoid side effects. While not
all methods need to be idempotent, maintaining a clear
structure enables users to effectively interact with the API.
Example
Key Point:Embrace Standard Methods for
Predictability
Example:Imagine you are integrating an API into your
application. By using standard methods like GET and
POST, you confidently navigate the complexities of data
retrieval and submission. As you call GetChatRoom() to
retrieve conversation data, you realize its predictable
behavior lets you focus on building great features
instead of deciphering complex commands. By adhering
to these standards, your product offers users a smoother,
more intuitive experience, allowing them to trust the
API's responses every time.
Critical Thinking
Key Point:Significance of Standard Methods in API
Design
Critical Interpretation:The chapter posits that standard
methods like GET and POST foster predictability,
easing user interactions; however, it's essential to
challenge this notion as different contexts may require
flexibility in API design. Analysts have debated the
'one-size-fits-all' approach, suggesting that specificity
can be more critical than standardization (see Fielding's
'Architectural Styles and the Design of Network-based
Software Architectures'). Organizations might benefit
from custom methods tailored to their unique
functionalities, indicating Geewax's viewpoint could
overlook the nuanced nature of software development.
 Chapter 9 Summary : 8 Partial updates
and retrievals
Section Content

Chapter Chapter 9: Partial Updates and Retrievals

Overview This chapter discusses the significance and implementation of partial updates and retrievals in API
design, essential for memory-sensitive applications like IoT devices.

8.1 Motivation Introduces two perspectives on resources: atomic units vs. granular attributes.

8.1.1 Partial Highlights the importance of requesting specific fields for efficiency as resources grow.
Retrieval

8.1.2 Partial Enables fine-grained modifications and maintains data integrity by preventing unnecessary overwrites.
Update

8.2 Overview Field masks are suggested as a tool for specifying fields to retrieve or update.

8.3 Explains how to transport field masks in GET and PATCH requests using query strings or headers.
Implementation

8.3.1 Transport Discusses embedding field masks in requests following HTTP guidelines.

8.3.2 Maps and Instructions for addressing nested structures in field masks.
Nested Interfaces

8.3.3 Repeated Challenges of updating/retrieving repeated fields; advises against using indices.
Fields

8.3.4 Default Defines default behavior for field masks regarding exceptional fields in retrieval.
Values

8.3.5 Implicit Field Describes inferring fields to update based on provided data (non-empty values).
Masks

8.3.6 Updating Mechanisms for removing keys from maps; challenges of dynamic structures discussed.
Dynamic Data
Structures

8.3.7 Invalid Recommends treating unspecified fields in masks as existing but null to avoid update errors.
Fields

8.3.8 Final API Definition of structures for API requests with field masks for retrieval and updates.
Definition

8.4 Trade-offs Partial updates and retrievals should not replace broader querying capabilities like GraphQL.

8.4.1 Universal Advocates for consistent partial retrieval support across all API resources.
Support

8.4.2 Alternative Mention of alternatives like JSON Patch, highlighting field masks' simplicity and effectiveness.
Implementations

8.5 Exercises Practical scenarios and questions for reinforcing partial retrievals and updates concepts.

Summary Partial retrievals are vital for large resources; partial updates minimize conflicts and maintain integrity.
Section Content

Field masks are key in specifying resources, and APIs should not allow index addressing for repeated
fields.

Chapter 9: Partial Updates and Retrievals

This chapter explores the importance and implementation of

partial updates and retrievals in API design. It discusses how
to update or retrieve specific fields of a resource without
needing full replacements, which is particularly crucial in
memory-sensitive applications like IoT devices.

8.1 Motivation

- Two perspectives on resources are introduced: atomic units

vs. granular attributes.

8.1.1 Partial Retrieval

- Traditional APIs retrieve entire resources, but as resources

grow, the ability to request only relevant fields becomes
essential for efficiency.
8.1.2 Partial Update

- Partial updates allow for fine-grained modifications and

maintain data integrity by preventing unnecessary overwrites.

8.2 Overview

- Field masks are suggested as a tool for specifying which

fields to retrieve or update in a resource.

8.3 Implementation

- Detailed explanations on how to transport field masks in

GET and PATCH requests despite HTTP constraints,
utilizing query strings or headers to specify fields of interest.

8.3.1 Transport

- Discusses how to embed field masks in requests while

adhering to HTTP guidelines.

Install
8.3.2 Maps Bookey App
and Nested to Unlock
Interfaces Full Text and
Audio
- Instructions for addressing nested structures and making
Chapter 10 Summary : 9 Custom
methods

Custom Methods

This chapter explores the need for custom methods in API

design, addressing scenarios where standard methods fail to
fit specific actions or operations, and emphasizing the
importance of maintaining a simple and predictable interface.

Motivation

There are occasions when specific actions, such as sending

emails or performing state changes, do not align well with
standard HTTP methods. Attempting to force these actions
into standard methods often creates confusion and
complexity in the API design. Custom methods offer a way
to accommodate these actions without bending the
established framework.

Why Not Just Standard Methods?

Although standard methods are often sufficient, they may not
adequately represent certain operations, especially state
changes. Using standard methods for actions with side
effects, such as updating an email's state while also triggering
external services, can lead to unpredictable behavior. Custom
methods can help manage these complexities while ensuring
the API remains intuitive.

Overview of Custom Methods

Custom methods are API calls that diverge from standard

methods and are not bound by the same rules and limitations.
Although they may create more freedom in implementation,
they lack the predictability associated with standard methods.
Therefore, it is crucial to establish consistent guidelines for
custom methods across the API.

Implementation

Custom methods primarily utilize the POST HTTP verb and

follow a specific path format to separate resource
identification from the action performed. Unlike standard
methods, which adhere to strict naming conventions and
restrictions, custom methods allow for more flexibility,
including the use of side effects—an aspect typically avoided
in standard methods.

Side Effects

Unlike standard methods, custom methods can include

actions with side effects, such as sending notifications or
interacting with multiple resources. This capability allows for
a clearer separation of concerns and a more organized
approach to API design.

Resources vs. Collections

Custom methods can target either specific resources or

collections. Choosing the right target depends on the nature
of the operation being performed. Generally,
collection-targeted methods are preferred when multiple
resources are involved, maintaining clarity and organization
within the API.

Stateless Custom Methods

Stateless custom methods are those that do not require the

preservation of state and can operate independently. They
serve as valuable tools, especially in scenarios with strict
data storage regulations.

Final API Definition

An example API definition illustrates the interplay between

standard methods and custom methods, showcasing how
custom methods facilitate various functionalities, such as
sending emails, archiving, or validating email addresses
while ensuring the overall API remains clean and intuitive.

Trade-offs

While custom methods enhance API flexibility and enable

complex operations, their existence may contravene RESTful
principles if overused. Proper design should ensure that
custom methods complement the resource architecture rather
than serve as a patch for poor designs.

Exercises

1. Explore the implications of requiring side effects during

resource creation and whether a custom method should be
used.
2. Discuss the circumstances under which custom methods
should target collections versus parent resources.
3. Analyze the risks associated with relying entirely on
stateless custom methods in API design.

Summary

Custom methods predominantly use the HTTP POST method

and should employ a colon to distinguish between the
resource and action. They may include side
effects—differently from standard methods—and should be
documented thoroughly. In general, when multiple resources
are involved, custom methods should prioritize collection
targets, reflecting careful consideration in balancing stateless
operations with the potential need for statefulness in the
future.
Critical Thinking
Key Point:The use of custom methods in API design
allows for unique operations that standard methods
cannot handle effectively.
Critical Interpretation:While J.J. Geewax presents a
compelling argument for the necessity of custom
methods to navigate complex operational scenarios,
readers should critically assess the potential pitfalls of
deviating from standard API practices. Custom
methods, although they can provide flexibility, may
introduce unpredictability and violate RESTful
principles if not implemented with caution. It's essential
to recognize that enforcing structured guidelines is
crucial to maintain API coherence and usability. As
stated by Martin Fowler in 'API Design Guidelines,'
consistency is key in API design to avoid evoking user
confusion, thereby suggesting that significant reliance
on custom methods could lead to an unclear or
inefficient API.
Chapter 11 Summary : 10 Long-running
operations

10. Long-Running Operations

This chapter explores how to manage long-running

operations in APIs, aimed at enhancing asynchronous
behavior for non-immediate calls, tracking operational
progress, and allowing users to interact with running
operations effectively.

10.1 Motivation

Traditional API methods are synchronous and immediate,

which is manageable for simple tasks. However, as
operations become more complex and resource-intensive,
this straightforward approach fails. The chapter outlines the
need for a new design pattern to handle these long-running
tasks, facilitating asynchronous methods while providing
consistent feedback during background execution.

10.2 Overview
The concept of Long-Running Operations (LROs) is
introduced, drawing parallels with existing programming
paradigms like Futures and Promises. LROs are designed to
track the background work done by an API, offering users
options to either wait for the results synchronously or handle
them asynchronously through callbacks.

10.3 Implementation

To support LROs, the chapter details how to:

- Define Operation resources with identifiers, results,
statuses, and metadata.
- Interact with LROs, including methods for checking status,
waiting for results, and managing operations (pause, resume,
cancel).
- Explore resource hierarchy and ensure effective discovery
of LROs across the API.

10.3.1 What Does an LRO Look Like?

An LRO interface comprises identifiers, status indicators,

results (or errors), and metadata about the operation's
progress. Specifying generic types allows for flexibility in
determining the nature of results and associated metadata.

10.3.2 Resource Hierarchy

LRO resources should be centralized in a top-level collection

for easier management and discovery, rather than nested
within the operations they pertain to. This improves query
efficiency across the system.

10.3.3 Resolution

Methods for resolving LROs can include polling for updates

or leveraging a wait mechanism within the API, allowing
users to retrieve results without unnecessary overhead.

10.3.4 Error Handling

LROs can encapsulate operational success or errors using a

structure that allows clients to differentiate between
API-level errors and those emanating from the operations
being tracked.

10.3.5 Monitoring Progress

Tracking progress is facilitated through a metadata field that
can provide updates on completion percentages, remaining
time, and other operational indicators.

10.3.6 Canceling Operations

APIs can offer mechanisms for canceling ongoing operations

through a dedicated `CancelOperation` method, which
ensures the user can request immediate cessation of
processing.

10.3.7 Pausing and Resuming Operations

Standardizing pause and resume functionalities allows users

to halt operations temporarily. The interface for this requires
a metadata field to track the paused state.

10.3.8 Exploring Operations

Developing a list method to retrieve all ongoing operations

adds visibility and control to users, allowing for management
of multiple LROs simultaneously.

10.3.9 Persistence
LROs should be treated as resources with a defined
persistence policy, potentially including expiration
mechanisms to purge outdated operations, avoiding storage
bloat.

10.3.10 Final API Definition

The final section consolidates all discussed components into

a comprehensive API definition outlining the various
methods and data structures required to implement LROs
effectively.

10.4 Trade-offs

LROs represent a powerful but complex pattern requiring

careful consideration of user interaction, resource
management, and operational control. They can ensure
efficiency and robustness in APIs dealing with potentially
long or indeterminate tasks.

10.5 Exercises

The chapter concludes with a set of exercises designed to

deepen understanding of LROs, dissecting their hierarchies,
expiration logic, and error handling scenarios.

Summary

Long-Running Operations (LROs) serve as the backbone for

managing background tasks in web APIs. They allow
tracking of progress, results, and errors, with options to
pause, resume, or cancel tasks as necessary. Persistence of
LROs and their metadata ensures effective management
without overwhelming system resources.
Example
Key Point:Efficiently Managing Long-Running API
Operations
Example:Imagine you're uploading a large video file
through an API. Instead of waiting for the upload to
finish, which could take a while, you can submit the file
and receive an immediate response with a unique
identifier. You can then use this ID to check the
progress, pause the upload if needed, or even cancel it
entirely if you change your mind. This LRO pattern not
only enhances user experience by preventing timeouts
but also keeps the server resources optimized.
Critical Thinking
Key Point:The complexity of Long-Running
Operations (LROs) and their patterns in API design.
Critical Interpretation:While J.J. Geewax presents LROs
as essential for managing asynchronous tasks, it is
important to question whether this design truly enhances
user experience or complicates operational workflows.
Critics like Gregor Hohpe suggest that increasing
complexity in API designs can lead to misinterpretations
and inefficiencies in frontend development (Hohpe,
2018). Furthermore, alternatives like reactive
programming paradigms, as discussed by Martin
Fowler, could potentially provide simpler solutions for
handling asynchronous operations without the overhead
of LRO management (Fowler, 2021). Thus, while LROs
may offer advantages, their implementation and
necessity should be critically evaluated against simpler
approaches.
 Chapter 12 Summary : 11 Rerunnable
jobs
Section Content

11. Rerunnable This chapter focuses on rerunnable jobs within APIs, discussing their concept, benefits over
Jobs long-running operations, and depiction as resources.

11.1 Motivation Rerunnable jobs are needed for asynchronous execution that requires configuration each time, allows for
permission separation, and automates scheduled job execution.

11.2 Overview Jobs are treated as distinct resources, separating work configuration from execution, simplifying
management, enhancing access control, and accommodating scheduling.

11.3 Involves defining Job Resource, Custom Run Method, and execution resources.
Implementation

11.3.1 Job Jobs are resources identified uniquely, storing configuration details, e.g., backups in a chat application.
Resources

11.3.2 Custom Executes preconfigured jobs via a unique run method, accepting only job identifiers and no additional
Run Method parameters.

11.3.3 Job An execution resource captures outputs from jobs without creating or modifying resources, allowing
Execution persistent access to results.
Resources

11.3.4 Final API Includes methods for creating, viewing, updating jobs, executing jobs, and listing job executions.
Definition

11.4 Trade-offs Although flexible, rerunnable jobs have trade-offs in permission management and retention policies for
execution resources compared to LROs.

11.5 Exercises Activities include exploring permission differences, discussing execution resource representation, and
evaluating the rationale of execution resource creation.

11. Rerunnable Jobs

This chapter focuses on rerunnable jobs within APIs,

explaining their concept, advantages over long-running
operations, and methods for depiction as resources.
11.1 Motivation

The need for rerunnable jobs arises in several scenarios

where:
- Asynchronous method execution requires configuration
every time invoked.
- It can separate permissions between executing the job and
configuring it.
- Scheduled job execution can be automated, avoiding the
complexities of client-side triggers.

11.2 Overview

Jobs are defined as a distinct resource in an API, separating

the configuration of work from its execution. Initially, a job
is created with the necessary configuration, followed by
invoking the job to perform the work later using a "run"
method. This separation simplifies management, enhances
control over access permissions, and accommodates
scheduling.

11.3Install Bookey App

Implementation to Unlock Full Text and
Audio
Supporting rerunnable jobs involves defining:
Chapter 13 Summary : 12 Singleton
sub-resources

Chapter 13: Singleton Sub-resources

Overview

This chapter discusses the concept of singleton

sub-resources, explaining their importance, implementation,
and the scenarios where they are beneficial. Singleton
sub-resources are used to handle specific components of data
that may need to change independently from their parent
resources, have different security needs, or be too large to
integrate directly.

12.1 Motivation

The chapter begins by addressing the motivation for using

singleton sub-resources, particularly in cases where
components that belong to a resource become impractical as
regular properties. For example, large access control lists
(ACLs) associated with a document may be inefficient if
stored with the document itself. Here, separating components
raises two key questions: when to split them and how to
implement this separation.

12.1.1 Reasons to Use a Singleton Sub-resource

Several reasons justify the use of singleton sub-resources:

-
Size or Complexity:
Large components may warrant separation to enhance
performance. For instance, binary data storage might be
better isolated from metadata to optimize data retrieval.
-
Security:
Certain data might have more stringent access controls
requiring separation to ensure proper security measures.
-
Volatility:
Components that are frequently updated can create
contention if kept as part of the main resource.

12.2 Overview of the Implementation

This section describes the structure of a singleton
sub-resource designed to be a hybrid between a full resource
and a simple property. They have unique properties and
methods that reflect their dual nature.

12.3 Implementation Details

Defining the interface for singleton sub-resources is crucial.

The section details how standard methods interact with these
sub-resources, highlighting:
-
Get and Update:
Function like standard resources, allowing retrieval and
modification.
-
Create:
Functions more like properties, automatically created
alongside the parent resource, requiring no explicit creation.
-
Delete:
Acts more like a property, indicating that deletion cascades
from the parent resource.

12.3.1 Methods Behavior

Standard methods behave similarly to regular resource
methods. There are clear guidelines on addressing singleton
sub-resources, with unique identifiers rather than relying on
parent identifiers.

12.3.2 Resetting

In some cases, there may be a need to reset to default values

after the parent resource is created. The API should support a
reset method to handle this, setting back to original values.

12.3.3 Hierarchical Considerations

A key point is that singleton sub-resources require a parent

resource and should not exist at the root level of the API
hierarchy. This eliminates potential contention issues and
ensures the separation remains meaningful.

12.3.4 Final API Definition

A sample API definition shows how Driver resources

integrate with DriverLocation singleton sub-resources,
emphasizing unique identifiers and the structure.
12.4 Trade-offs

The singleton sub-resource pattern offers benefits but comes

with trade-offs:
-
Atomicity:
Interaction with both the parent and sub-resource
simultaneously is not feasible.
-
Exactly One Sub-resource:
The pattern limits sub-resources to a single instance,
distinguishing it from traditional collections.

12.5 Exercises

The chapter concludes with exercises designed to deepen

understanding of singleton sub-resources, questioning
considerations for separation, method support, and hierarchy
limitations.

Summary

This chapter provides insights into the design and

implementation of singleton sub-resources, exploring their
motivations, benefits, specific behaviors, and potential
trade-offs within API design.
Chapter 14 Summary : 13 Cross
references

Summary of Chapter 14: Cross References

Overview

This chapter discusses the relevant patterns for referencing

resources in APIs, focusing on naming conventions, handling
referential integrity, and the necessity of potentially storing a
copy of resource data. It emphasizes the common scenario
where resources need to link to one another, while also
highlighting the complexity that arises in managing these
references consistently.

Motivation

Resources are interconnected, requiring a method for

references that address both local and global contexts. While
referencing might seem straightforward, there are numerous
implementation details that can lead to inconsistencies. This
chapter sets out guidelines for resource references to ensure
clarity and consistent behavior.

Implementation

The chapter delves deeper into the specifics of how one

resource should reference another, highlighting:
-
Reference Field Naming
: It's advisable to name fields in a way that conveys the type
and purpose of the resource being referenced (e.g., using
"authorId" for a reference to an Author).

-
Data Integrity
: The potential for dangling pointers arises when resources
are deleted without checking their referential integrity.
Options include prohibiting deletions or allowing them with
appropriate handling.
-
Value vs. Reference
: The chapter contrasts the approaches of storing a reference
(pointer) versus a copy of the resource's data, discussing the
trade-offs in terms of freshness versus convenience,
performance, and data consistency.

Final API Definition

Examples are provided to illustrate the proper setup of

interfaces for referencing resources, emphasizing the need for
clarity in naming and validation.

Trade-offs

The reliance on references may require multiple API calls to

access related data or necessitate using tools like GraphQL
for efficient data retrieval.

Exercises

The chapter concludes with exercises prompting discussions

on when it might be appropriate to store a copy of resource
data versus relying solely on references and the implications
of altering the rules on referential integrity.

Summary Points

- Reference fields should be string identifiers, typically

ending with "ID."
- Fields holding copies of resource data should not have this
suffix.
- References are often unreliable over time, as they may not
be maintained with resource deletions.
- Resource data may be stored inline but risks becoming stale
with updates to the original.
Chapter 15 Summary : 14 Association
resources

Chapter 15: Association Resources

This chapter discusses how to effectively manage

many-to-many relationships through association resources in
API design.

14.1 Motivation

Many API resource relationships are simple, typically

unidirectional. However, complex many-to-many
relationships, like those involving users and groups, require a
more sophisticated modeling approach. Using a separate
association resource allows for better management of these
connections and related metadata.

14.2 Overview

Many-to-many relationships in relational databases are often

represented by join tables. Exposing these associations as
accessible API resources enhances usability. Creating,
listing, and managing these associations through standard
methods ensures clarity and provides metadata for
relationships.

14.2.1 Association Alias Methods

To facilitate common queries regarding associations, we can

provide convenient aliases. These allow easier access to
questions such as "What groups is this user a member of?" by
representing associations in a more user-friendly manner.

14.3 Implementation

14.3.1 Naming the Association Resource

Choosing an appropriate name for the association resource

(e.g., Membership) is crucial and should reflect the context
of the application.

Install
14.3.2 Bookey
Standard AppBehavior
Method to Unlock Full Text and
Audio
Key methods (create, get, list, update, delete) are essential for
Chapter 16 Summary : 15 Add and
remove custom methods

Chapter 16: Add and Remove Custom Methods

Overview

This chapter discusses managing many-to-many relationships

through custom add and remove methods, focusing on an
alternative pattern that allows consumers to associate
resources without a separate association resource.

15.1 Motivation

The need to manage the relationships between resources,

particularly in many-to-many scenarios, is explored.
Although the association resource pattern is flexible, this
chapter investigates whether a simpler and more intuitive
method exists, accepting certain limitations.

15.2 Overview
A simpler way to handle many-to-many relationships is
outlined, which involves hiding association resources and
using custom methods to manipulate relationships directly.
The add and remove methods serve as shortcuts, creating or
deleting associations without exposing intricate details.

15.3 Implementation

After identifying the managing resource, custom add and

remove methods are defined, formatted as
Add<Managing-Resource><Associated-Resource>. These
methods accept a request with a parent resource identifier
and operate on the association's identifier alone for
simplicity. Listing methods are introduced for retrieving
associated resources.

15.3.1 Listing Associated Resources

Methods are provided to list users in a group and groups a

user belongs to, employing pagination and filtering.

15.3.2 Data Integrity

Issues regarding duplicate data and conflicts when adding or
removing associations are discussed. Appropriate error
responses (e.g., 409 Conflict, 412 Precondition Failed) are
suggested to ensure data integrity.

15.3.3 Final API Definition

An example of the implementation highlights the simplicity

of the add/remove pattern while acknowledging the absence
of metadata storage for relationships.

15.4 Trade-offs

The chapter contrasts the simplification gained by avoiding a

full association resource with the functional limitations
imposed, such as nonreciprocal relationships and lack of
relationship metadata.

15.4.1 Nonreciprocal Relationship

Choosing between a managing resource and a managed

resource can sometimes be counterintuitive, which is a
drawback of this method.
15.4.2 Relationship Metadata

This pattern does not allow for storing relationship-related

metadata, constraining the information beyond the mere
existence of the relationship.

15.5 Exercises

The exercises encourage thinking about when to use custom

methods, identifying managing resources, and understanding
expected outcomes in scenarios involving duplicates.

Summary

The use of custom add and remove methods simplifies the

management of many-to-many relationships when
association resources are excessive, focusing on the direct
addition or removal of an associated resource to a managing
resource.
Chapter 17 Summary : 16 Polymorphism

Polymorphism

This chapter discusses polymorphism in API design,

explaining its benefits, structure, and guidelines for use.

1. Motivation

Polymorphism allows objects to utilize common interfaces

while minimizing implementation details. For instance,
different shapes like Triangles and Squares may implement a
shared interface Shape, enabling a consistent approach when
interacting with various types.

2. Overview

Polymorphic resources feature a generic interface with

explicit fields indicating specific resource types. This
approach prevents method duplication and promotes a
unified method like ListShapes instead of separate methods
for each shape type. Validations are essential for managing
data fields related to these different types.
3. Implementation

3.1 Deciding When to Use Polymorphic Resources

When resource types show commonality, using a

polymorphic resource might be appropriate. However,
decisions should consider API behavior and user interaction
with the resources.

3.2 Polymorphic Structure

Polymorphic resources require a type field to specify

subtypes. Using a string for the type field and ensuring
proper validation is crucial. The structure should facilitate
flexibility without making future modifications cumbersome.

3.3 Polymorphic Behavior

API methods designed for polymorphic resources should

behave similarly to traditional resources. However, there can
be complications when the same method operates on
different resource types.
3.4 Why Not Polymorphic Methods?

Polymorphic methods that act on multiple resource types

have inherent risks. Resource behavior can differ
significantly, making it unsafe to rely on a single method for
varied resources. This approach can reduce flexibility and
introduce future complications.

4. Trade-offs

Polymorphism is powerful but can complicate API design.

It's essential to evaluate if the resources represent different
types of a generic resource. Polymorphic resources are
preferable over polymorphic methods to maintain future
flexibility.

5. Exercises

1. Should a folder and bookmark be a single polymorphic

resource? Explain.
2. Why use a string for polymorphic types instead of an
enumeration?
3. Why ignore additional data like a radius for a square rather
than returning an error?
4. Discuss the drawbacks of polymorphic methods.
5. Why is it unwise to maintain a polymorphic set of standard
methods?

Summary

Polymorphism in APIs enables resources to adopt varying

types to avoid code duplication. It’s advisable when users
expect to list different resource types collectively. The type
information should be a mutable string, with validations
focusing on the presence of required data. Avoid
polymorphic methods as they restrict future adaptability.
Chapter 18 Summary : 17 Copy and
move

Copy and Move

This chapter explains how to use custom methods for

copying and moving resources in an API. It covers choosing
appropriate identifiers, handling child resources, managing
external data references, and determining expected atomicity
levels for these operations.

17.1 Motivation

In a perfect world, resources in APIs would never need to be

renamed or relocated. However, users may make mistakes,
necessitating the ability to move or duplicate resources. The
goal is to provide a safe and stable method for handling these
operations.

17.2 Overview

Standard update methods can't be used for moving or

copying resources, leading to the use of custom methods
instead. Important details arise, like how to handle identifiers
and related resources when copying or moving.

17.3 Implementation

Implementation of custom methods for copying and moving

requires attention to unique identifiers. The API service
should manage identifier generation to avoid user errors.

17.3.1 Identifiers

During copying, user-specified identifiers should be treated

similarly to standard create methods. The copy request may
include a destination ID if supported. Moving resources
requires identifying the new parent or renaming with valid
identifiers.

17.3.2 Child Resources

When copying or moving, all associated child resources must

alsoInstall Bookey
be handled App to
accordingly Unlockconsistency
to maintain Full Textwithin
and
the API. Audio
Chapter 19 Summary : 18 Batch
operations

Chapter 19: Batch Operations

This chapter discusses batch operations in APIs, outlining

how they differ from standard methods and the importance of
atomicity.

18.1 Motivation

Batch operations allow users to manipulate multiple

resources in bulk, enhancing efficiency by reducing the need
for multiple API calls. Atomicity ensures that either all
operations succeed or none do, which is vital when
operations on multiple resources are interdependent.

18.2 Overview

The chapter proposes methods akin to standard API methods

that allow atomic operations on groups of resources. These
methods include BatchGet, BatchCreate, BatchUpdate, and
BatchDelete.

18.3 Implementation

Custom methods support batch operations, defined to

maintain atomicity. Key areas include:
-
Atomicity:
All operations in a batch must either fully succeed or fail.
-
Operation on Collections:
Methods should target collections rather than individual
resources.
-
Ordering of Results:
The order of resources in requests must be matched in
responses to keep consistency.
-
Common Fields:
Batch methods may hoist common fields to reduce
redundancy.
-
Operating Across Parents:
Utilizing wildcards can help support operations involving
multiple parents.

18.3.6 Batch Get

This method retrieves a set of resources based on unique

identifiers, emphasizing the necessity of atomicity and the
preservation of order in responses.

18.3.7 Batch Delete

Similar to Batch Get but focused on deleting resources. This

operation must also be atomic, failing if any single resource
cannot be deleted.

18.3.8 Batch Create

This method creates several new resources atomically. It

requires distinct handling of parent field allocation, ensuring
that the intended parent is accurately associated with each
resource being created.

18.3.9 Batch Update

Similar to Batch Create, this method updates multiple

resources atomically while allowing for partial updates via
field masks. It ensures uniformity in field application without
conflicts.

18.3.10 Final API Definition

The chapter consolidates all previously discussed methods,

providing a complete API design for supporting batch
operations, enabling effective resource management through
single API calls.

18.4 Trade-offs

The chapter discusses the implications of prioritizing

atomicity over simplicity, resulting in potentially
inconvenient user experiences but fostering consistency in
API behavior.

18.5 Exercises

This section poses questions aimed at reinforcing key

concepts regarding batch operations, atomicity, and ordering
of results.
Summary

Batch methods must be atomic, adhere to a consistent

naming convention of Batch<Method><Resources>(), and
generally operate on collections rather than individual parent
resources. Results should maintain the order in which
resources or requests were originally sent, with a wildcard
character used to denote multiple parents in individual
requests.
Critical Thinking
Key Point:The importance of atomicity in batch
operations
Critical Interpretation:The chapter highlights atomicity
as crucial for batch operations in API design, ensuring
all actions succeed or fail together. However, this
perspective may overlook the potential benefits of
simpler, non-atomic operations that could provide
flexibility in less critical contexts. For instance, some
argue that non-atomic operations can improve user
experience by allowing partial successes, a view
supported by sources like 'RESTful Web Services' by
Leonard Richardson and Sam Ruby, which emphasizes
balancing flexibility and reliability in API interactions.
Chapter 20 Summary : 19 Criteria-based
deletion

Criteria-Based Deletion

This chapter discusses the use of a custom purge method for

deleting resources that match specific criteria, highlighting
its potential dangers and providing safety measures to
prevent unintended data loss.

19.1 Motivation

Batch deletion usually requires knowing the unique

identifiers of resources. This method is straightforward but
often impractical for cases where the user wants to delete
resources based on criteria rather than specific IDs. The
chapter illustrates an example where a user wants to delete
archived chat rooms but must first identify these resources.

19.2 Overview

The purge method consolidates the actions of searching for

and deleting resources in a single API call, in contrast to the
previous method that required multiple calls. However, it
poses risks as it allows extensive deletions without full user
awareness.

19.3 Implementation

The chapter describes the process flow of the purge method,

incorporating safety measures like requiring a 'force' flag for
executing deletions and providing a preview of items that
would be deleted.
-
19.3.1 Filtering Results

The filter in the purge method operates similarly to that in

the standard list method, potentially leading to catastrophic
results if misconfigured.
-
19.3.2 Validation Only by Default

The purge method defaults to validation to prevent

accidental deletions, with explicit user confirmation required
for actual deletions.
-
19.3.3 Result Count

The purge response includes a count of matching resources,

providing estimates during validation requests to prevent
overload in computation.
-
19.3.4 Result Sample Set

To enhance user confidence, the method returns a sample

set of identifiers for review before deletion.
-
19.3.5 Consistency

The chapter discusses the risks of data inconsistency during

validation and actual deletion due to changes in the dataset.
-
19.3.6 Final API Definition

The API definition is provided for the purge method,

outlining its structure and expected parameters.

19.4 Trade-offs

The purge method inherently poses a high risk of mass data

loss and should be used only in critical situations. It is
likened to providing users with significant destructive power
through the API.

19.5 Exercises

The chapter concludes with exercises that encourage

reflection on the conditions under which implementing the
purge method is appropriate, the implications of an empty
filter, and considerations for soft deletion behavior.

Summary

The custom purge method enables deletion of multiple

resources based on specific criteria but should be utilized
sparingly. Requests default to validation mode to minimize
data loss risks, with all responses conveying a count of
affected resources and a sample set for verification.
Chapter 21 Summary : 20 Anonymous
writes

Chapter 21 Summary: Anonymous Data in API

Design

Overview of Anonymous Data

This chapter discusses the concept of anonymous data and

how to ingest data into an API without creating identifiable
resources. It highlights scenarios where data must be created
without unique identification, such as log entries or time
series data points intended for aggregation.

Motivation

Traditionally, API data handling involves managing

identifiable resources. However, there are cases (e.g.,
collecting time series statistics) where users are more
interested in aggregates than individual data points. The
chapter questions how to insert data into the API when
unique identifiers for data points are not applicable,
proposing the idea of a specialized method for data ingestion.

Implementation of the Write Method

The chapter introduces the `write` method, a custom function

to insert new data without returning an identifiable resource.
Instead of allowing access to specific entries, users can only
request aggregate data. The write method does not return any
data; it may either return nothing or a success/error status. It
also details how to structure the request and define the
appropriate HTTP URL binding.

Consistency Considerations

When using the write method, the chapter emphasizes that

users should not expect immediate visibility of their data
entries. Instead, the method can respond immediately (with
an HTTP 202 Accepted response) while data is processed in
the background, aligning with events typical in large-scale
analytics systems.
Install Bookey App to Unlock Full Text and
Final API Definition Audio
Chapter 22 Summary : 21 Pagination

Pagination

This chapter discusses the importance of pagination in APIs,

allowing users to consume large data sets in smaller,
manageable chunks rather than overwhelming them with a
single large response.

21.1 Motivation

As resources in APIs grow, it becomes unreasonable to

retrieve all data in one request. The chapter emphasizes the
need to split data into smaller partitions or pages, addressing
how to effectively allow consumers to interact with large
datasets.

21.2 Overview

Pagination allows a consumer to request data in chunks, akin

to flipping through pages in a book. Using cursor-based
pagination, APIs can supply a current chunk of data along
with a token for retrieving the next one.
21.3 Implementation

The pagination pattern relies on three key fields:

1.
pageToken
: An opaque identifier for continuation.
2.
maxPageSize
: Consumer-specified maximum results desired.
3.
nextPageToken
: Used to request more results.

21.3.1 Page Size

Setting a maximum page size rather than an exact number of

results allows for better performance and flexibility,
especially in large-scale systems. Reasonable defaults for
maximum page sizes should be established, with clear
documentation.

21.3.2 Page Tokens

Page tokens serve as cursors for continuation but should be
opaque to consumers. Their structure should remain hidden
to avoid implementation leaks.

21.3.3 Total Count

Including a total count of results can be computationally

expensive in large datasets. It’s advisable to avoid this unless
absolutely necessary.

21.3.4 Paging Inside Resources

In some cases, large resources may require pagination within

themselves. This can be handled similarly to collections by
breaking the resource into chunks and employing
continuation tokens.

21.4 Trade-offs

21.4.1 Bi-directional Paging

The pagination pattern does not support backward

navigation, which may be a limitation for some user
interfaces. Cached results can be helpful in such cases.

21.4.2 Arbitrary Windows

Direct access to specific page numbers is not possible,

requiring reliance on filtering and ordering for navigation.

21.5 Anti-pattern: Offsets and Limits

Using offsets and limits can leak implementation details and

lead to inconsistencies. This common practice should
generally be avoided in APIs.

21.6 Exercises

The chapter includes questions to reinforce the concepts of

pagination, such as the importance of maximum page size
and the conditions for determining when pagination is
complete.

Summary

Pagination effectively enables the handling of large

collections or single resources in manageable chunks through
three specific fields:
maxPageSize
,
pageToken
, and
nextPageToken
. The completion of pagination is indicated by the absence of
a next page token in the response.
Chapter 23 Summary : 22 Filtering

22. Filtering

This chapter discusses essential aspects of implementing

filtering in standard list methods of APIs. It addresses how to
effectively support filtering resources by introducing filter
expressions in requests and offers guidelines for expected
behaviors.

22.1 Motivation

The chapter begins by highlighting the limitations of existing

methods to retrieve resources. While standard methods like
list and get are straightforward, they fail to address scenarios
where users need to browse a specific subset of resources
based on defined criteria. The chapter suggests using the
server to handle filtering instead of clients needing to fetch
and evaluate unnecessary resources.

22.2 Overview

A proper design alternative is proposed where filtering

criteria are sent to the API server for processing, rather than
the client fetching complete datasets. It emphasizes the need
for a well-defined structure for the filter criteria, while also
addressing crucial decisions regarding what filtering
functionality should be supported, including whether to allow
comparisons based on complex data relationships.

22.3 Implementation

The implementation section outlines how to communicate

filters to the API server efficiently and examines various
structure options, differentiating between structured and
unstructured query representations.

22.3.1 Structure

Different approaches for structuring filters are discussed,

weighing the pros and cons of string-based queries (like
SQL) against structured query interfaces (like MongoDB).
Although both options can achieve similar results, the choice
often revolves around simplicity and adaptability for clients.

22.3.2 Filter syntax and behavior

The syntax rules for filter strings are defined, emphasizing
that while string queries are fundamentally simple, they must
adhere to specific rules to remain valid. Practical
considerations of execution time, resource isolation, and
performance during evaluations are also addressed.

22.3.3 Final API definition

The chapter concludes with the final API definition,

showcasing how to incorporate a filter field into a request
structure, reinforcing that filter criteria should be represented
as strings for increased flexibility.

22.4 Trade-offs

Key trade-offs in implementing filtering are examined. While

adding filtering can initially appear resource-intensive, the
long-term benefits for users, who can avoid fetching entire
data sets, outweigh the costs. Using unstructured filter strings
can ease future updates and maintenance compared to
structured filters.

22.5 Exercises
This section provides exercises to prompt critical thinking
about filtering strategies, the implications of structure versus
unstructured filtering, and error handling in filter evaluations.

Summary

The chapter summarizes the benefits of supporting filtering

in standard list methods, arguing for string-based filter
specifications for simplicity and flexibility. It advises
limiting resource comparisons to avoid excessive execution
time and stresses the immediate reporting of evaluation
errors for better usability in API design.
Chapter 24 Summary : 23 Importing and
exporting

Importing and Exporting

This chapter details patterns for safely and flexibly importing

and exporting resources through an API, prioritizing direct
communication with external storage systems over using an
intermediary client. It emphasizes the use of loosely coupled
configuration structures to maximize flexibility and
reusability.

23.1 Motivation

APIs managing user data should enable efficient resource

transfer directly to and from the external storage system. The
chapter illustrates common issues in data handling, like
inefficient routes for data transport, and proposes solutions to
mitigate them.

23.2 Overview
The chapter outlines two primary methods: `import` and
`export`, responsible for moving data between the API and
external storage, and converting API resources into raw
bytes. A flexible configuration interface is vital to adapt to
diverse storage systems and serialization formats.

23.3 Implementation

Focuses on implementing custom import and export

methods. Each method handles specific resource types,
returning a promise due to potentially long processing times.
-
23.3.1 Import and Export Methods
: Defines methods responsible for managing data complexity
and creating new resources.
-
23.3.2 Interacting with Storage Systems
: Highlights the necessity of configuring each storage system
independently to avoid confusion.
-
23.3.3 Converting Between Resources and Bytes
Install mechanisms
: Discusses Bookey App to Unlock
for data Fulland
serialization Text and
the need
Audio
for additional transformations like compression or
encryption.
Chapter 25 Summary : 24 Versioning
and compatibility

Versioning and Compatibility

This chapter covers:

- Definition and importance of versioning
- Understanding compatibility
- Backward compatibility specifics
- Trade-offs in versioning strategies
- Overview of popular versioning strategies for web APIs
The software we build is rarely static; it evolves as new
features are added. This creates a challenge: how to
implement improvements without disrupting users'
experiences with the existing API. The solution lies in
versioning.

Motivation

Software development usually involves checkpoints or

launches with new features that require visible updates to
users, especially for web APIs. As APIs are public and rigid,
changes must be made cautiously to avoid inconveniencing
current users. The text explores how to introduce versioning
to manage these changes effectively.

Overview of Compatibility

Compatibility refers to the capability of different

components, particularly the interaction between a client and
a server. With multiple versions of both clients and APIs,
ensuring successful communication paths becomes complex.
The goal is to implement changes that do not disrupt existing
user experiences.

Defining Backward Compatibility

Backward compatibility allows new functionality to be

introduced without affecting existing users. It's essential to
ask whether changes could cause existing code to break. No
single answer defines backward compatibility; it varies based
on user expectations and requirements.

Handling Changes in Functionality

1.
Adding Functionality:
Introducing new features can be done in ways that don't
disrupt existing users.
- Changes can be in the form of new fields or
functionalities, but they must be compatible with existing
client expectations.
2.
Fixing Bugs:
Fixing errors often introduces added complexity as some
bugs may lead to behavior changes that could affect users.
3.
Mandatory Changes:
Some changes are imposed by laws or regulations
necessitating a careful balance in how these changes are
implemented.
4.
Under-the-Hood Changes:
This includes subtle changes like performance optimizations
which, while beneficial, can lead to different user
experiences.
5.
Changing Semantics:
Introduces more complex behavioral changes in received
signals or meanings of resources. Careful evaluation of user
impact is crucial.

Implementation of Versioning Strategies

Choosing a versioning strategy involves understanding the

various approaches and their implications:
-
Perpetual Stability:
A commonly used strategy that maintains stability by having
a stable version forever.
-
Agile Instability:
This involves a sliding window of active versions,
promoting flexibility but potentially compromising long-term
stability.
-
Semantic Versioning:
A method that uses a structured versioning system where
changes in three numeric segments convey specific
information about compatibility and function.

Trade-offs in Versioning

Ultimately, decisions around versioning and compatibility

must balance several trade-offs:
-
Granularity vs. Simplicity:
More granularity offers users precise control but can create
overwhelming choices.
-
Stability vs. New Functionality:
Decisions about stability may limit access to new features
that some users desire.
-
Happiness vs. Ubiquity:
Ensuring all users are satisfied while maximizing usability
across different user demographics makes it difficult to find a
one-size-fits-all solution.

Summary

Versioning is essential for evolving APIs while minimizing

disruptions. Compatibility refers to whether changes affect
existing users, and the definition of digital compatibility is
often subjective. Various strategies exist, each offering
unique benefits and trade-offs related to user preferences and
operational complexities. Understanding these factors allows
designers to create APIs that effectively balance user needs
with functional improvements.
Critical Thinking
Key Point:The importance of versioning in API
design is subjective and contingent on user context.
Critical Interpretation:While J.J. Geewax emphasizes
the necessity of versioning to ensure backward
compatibility and user experience, it's crucial to
recognize that not every API design may benefit equally
from such meticulous strategies. The effectiveness of
versioning often varies based on the specific user base,
the scale of the API, and the nature of the modifications
being made. For instance, some argue that
over-engineering APIs with complex versioning can
lead to unnecessary complications, potentially alienating
users rather than aiding them (Sussman, G. 'Software
engineering for high performance'). Therefore, while
Geewax's arguments present valid considerations for
many scenarios, the balance of trade-offs in versioning
must be tailored to fit the unique circumstances and
requirements of each API.
Chapter 26 Summary : 25 Soft deletion

Soft Deletion

This chapter discusses the concept of soft deletion in APIs,

where resources are marked as deleted but not permanently
removed. This approach allows data recovery in case of
accidental deletions, acting like a "Recycle Bin" for
resources.

25.1 Motivation

Soft deletion was motivated by the user experiences with

Windows 95's Recycle Bin, illustrating the need for a
recoverable delete action in APIs. Mistaken deletions in
coding or scripting can lead to significant data loss,
emphasizing the importance of having a mechanism to hide
rather than remove resources.

25.2 Overview

Implementing soft deletion involves adding a deleted status

to resources—either as a Boolean flag or a state within an
enumeration. The standard delete method is modified to
update this status rather than remove the resource. Custom
methods for undeleting and permanently expunging
resources are also introduced.

25.3 Implementation

-
25.3.1 Deleted Designation
: A Boolean flag is the simplest way to mark a resource as
deleted, set to false by default. Code attempts to update this
field should be ignored.

-
25.3.2 Modifying Standard Methods
: Adjustments are needed for existing methods. For instance,
the get method should return soft-deleted resources instead of
raising a 404 error, while the list method must exclude
deleted resources unless requested otherwise.
-
25.3.3 Undeleting
: A custom undelete method is established to allow recovery
of soft-deleted resources. It should provide an error response
if the resource isn't marked as soft-deleted.
-
25.3.4 Expunging
: The expunge method is introduced for full deletion,
separate from soft deletion to retain the ability to
permanently remove resources.
-
25.3.5 Expiration
: Resources can have expiration times for automatic
permanent deletion after a defined period, similar to email
policies in providers like Gmail.
-
25.3.6 Referential Integrity
: Existing referential integrity rules are maintained, ensuring
that the relationships in the database remain intact and
unbroken regardless of soft-deletion.
-
25.3.7 Effects on Other Methods
: Related methods, like batch delete, should also support the
soft delete behavior established for standard methods.
-
25.3.8 Adding Soft Delete Across Versions
: Introducing soft deletion in an API previously only
supporting hard deletion can be complex. Such changes
should prioritize backward compatibility and may warrant
versioning.

25.3.9 Final API Definition

A fully defined interface is suggested for implementing soft

deletion in API interactions, incorporating soft deletion
requirements across standard methods.

25.4 Trade-offs

Implementing soft deletion is a trade-off between allowing

users to permanently remove data versus preventing
accidental data loss. Such decisions should consider the
nature of the data and applicable regulations regarding data
handling.

25.5 Exercises

Reflective questions encourage consideration of scenarios

involving soft deletion's design and implementation, such as
when to use Boolean flags versus state fields, handling
undelete and expunge operations, and implications for
existing API behavior.
Summary

Soft deletion allows marking resources as deleted without

physical removal, supporting recovery efforts. It involves
implementing modified standard methods, custom undelete
and expunge methods, maintaining referential integrity, and
considering expiration policies for deleted resources.
Existing referential integrity measures should apply, keeping
in mind any regulatory requirements.
Chapter 27 Summary : 26 Request
deduplication

Chapter 27: Request Deduplication

Introduction

This chapter explores the concept of using request identifiers

to prevent duplicate requests, manage collisions, and strike a
balance between caching and consistency in web APIs.
Given the unreliability of networks, retries are often
necessary, particularly for non-idempotent methods.

26.1 Motivation

Modern networks exhibit a level of unreliability, leading to

scenarios where requests may not reach servers or responses
may not return to clients. In the case of non-idempotent
methods, this poses a risk of duplicate work when retries
occur without assurance of the original request's outcome.
26.2 Overview

The pattern discussed introduces providing unique request

identifiers to ensure requests are processed only once. Proper
handling of duplicate requests is essential to maintain
functionality and provide meaningful feedback rather than
errors.

26.3 Implementation

26.3.1 Request Identifier

A unique ID field for requests prevents duplication.

However, since users often choose their identifiers poorly,
strict format and selection guidelines are necessary.

26.3.2 Response Caching

Responses are cached based on the request identifier. If the

same ID is submitted, the cached response is returned instead
Install Bookey
of reprocessing App to Unlock Full Text and
the request.
Audio
26.3.3 Consistency
Chapter 28 Summary : 27 Request
validation

Request Validation

Overview

This chapter discusses the importance of pre-request

validation in APIs, particularly for unsafe methods. It
introduces a special field, `validateOnly`, that allows
developers to preview what the outcome of a request would
be without executing it.

Motivation

APIs can be complex and confusing. Users often make

mistakes when trying to verify the correct execution of
methods, especially unsafe ones. The chapter emphasizes the
need for a validation mechanism to reduce human error and
avoid unintended consequences in production systems.
Implementation

The chapter suggests adding a Boolean field (`validateOnly`)

to request interfaces. When this flag is true, the system
should perform validations such as permission checks,
conflicts, and referential integrity without making actual
changes. Validation responses should mirror what the
response of a normal request would have been.

External Dependencies

Requests can involve external services that complicate the

validation process. The chapter advises to respect the safety
and idempotence rules when dealing with these externalities.
If validation can't be thoroughly achieved due to these
dependencies, necessary fallbacks should be employed, such
as checking input formats.

Special Side Effects

The chapter discusses scenarios where validation requests

could yield confusing outcomes. It introduces the idea of
returning plausible responses based on given conditions even
in random or contingent scenarios, ensuring consistency in
responses.

Final API Definition

The conclusion presents a simplified definition of the API

that includes the `validateOnly` field, providing a practical
implementation solution that adheres to safety and
idempotence standards.

Trade-offs

While validation requests offer users a way to mitigate risks

without executing actions, they are more of a convenience
than a necessity. Supporting these requests can help
minimize the cost of expensive API methods.

Exercises

The chapter provides questions that challenge readers to

think critically about the importance of the `validateOnly`
flag, the implications of communicating with remote services
during validation, and the rationale behind default values for
validation flags.
Summary

The chapter concludes that allowing users to validate API

requests via the `validateOnly` field is crucial for preventing
dangerous actions. It promotes a balance between
functionality and safety across methods interacting with
external services, while acknowledging inherent limitations.
Chapter 29 Summary : 28 Resource
revisions

Chapter 29 Summary: Resource Revisions

Overview of Resource Revisions

This chapter discusses methods for safely storing and

managing multiple revisions of resources over time. It
highlights how to identify, create, list, retrieve, and restore
individual revisions and the handling of child resources
associated with revisable resources. The focus is on
preserving history and enabling functionalities like rolling
back to previous revisions.

Motivation

Traditional APIs capture only the current state of resources

without considering past states. This chapter emphasizes the
importance of tracking revision history, especially for
resources that are legally significant or undergo frequent
changes, using examples from document editing and contract
management.

Implementation Details

To implement resource revisions, a new concept called

"resource revision" is introduced, which comprises a
snapshot of the resource with a unique identifier and a
timestamp. Two new fields—revision identifier and a
creation timestamp—are added to existing resource
definitions to support multiple revisions while maintaining
the same interface.

Creating Revisions

There are two strategies for creating revisions: implicitly

(automatically on resource changes) and explicitly (upon user
request). The preferred method is to create revisions
implicitly since it ensures comprehensive history without
user intervention. However, explicit revisions allow users to
have more control when necessary.

Retrieving and Listing Revisions

Retrieving a specific revision can be done by appending a
revision identifier to the resource ID using a special separator
character. This chapter also provides methods for listing all
revisions associated with a specific resource, allowing users
to browse revisions similarly to standard resource listings.

Restoring Revisions

Restoring a resource to a previous state involves creating a

new revision based on an older one, ensuring that the
historical record remains intact and allowing users to revert
to any previous state without losing revision history.

Deleting Revisions

The necessity for a method to delete revisions stems from the

need to manage sensitive data effectively. A distinct API
endpoint should be created for this purpose to avoid
confusion with deleting the entire resource or its current
revision.

Handling Child Resources

The chapter discusses whether child resources should be

included in a resource's revision history. Generally, it
recommends focusing revisions on a single resource, unless
specific business requirements necessitate tracking child
resources as well.

Final API Definition

The chapter concludes with a finalized API definition for

managing revisions, including methods for creating,
retrieving, listing, restoring, and deleting resource revisions,
while maintaining a consistent interface for users.

Trade-offs

Though resource revisions provide valuable historical

context, they also increase API complexity and storage
requirements. If feasible, they should be avoided unless
necessary for specific use cases.

Exercises

Several exercises encourage readers to consider scenarios for

implicit vs. explicit revisions, rationale for identifier choices,
and implications of revision restoration practices.
Conclusion

Resource revisions are vital for tracking the state of resources

over time, supporting various implementations for creation,
retrieval, and management, while ensuring the integrity of
historical data.
Chapter 30 Summary : 29 Request
retrial

Request Retry

This chapter addresses strategies for managing failed API

requests, including criteria for safe retries, advanced timing
algorithms, prevention of stampeding herds, and guidance for
client retries dictated by APIs.

Motivation

Web APIs often experience failed requests due to either client

errors or transient server issues. In cases of transient errors, it
is beneficial to implement a retry mechanism for requests
that encounter failures but are not fundamentally flawed.
Differentiating between types of errors helps determine
which requests warrant a retry, with emphasis on HTTP error
codes; for instance, 500-level errors are typically retriable,
while 400-level errors often indicate issues with the request
itself.
Overview

The goal is to minimize retries while maximizing successful

request responses. This involves providing clients with a
clear algorithm for retrying requests and, when applicable,
informing them of specific timing for retries based on server
availability.

Client-side Retry Timing

The chapter discusses the use of an exponential back-off

algorithm for timing between retries, where delays double
with each subsequent failure. This approach is effective in
undefined network conditions but may not always be the best
for web APIs.

Server-specified Retry Timing

In scenarios with server knowledge about retry eligibility,

explicit instructions to clients can enhance retry success. API
services can communicate specific wait times to suppress
Install
reliance Bookey App
on exponential to Unlock
back-off in certainFull Text and
contexts.
Audio
Implementation
Chapter 31 Summary : 30 Request
authentication

Request Authentication

This chapter discusses the fundamental requirements for a

request authentication system using digital signatures.

Overview of Digital Signatures

Digital signatures ensure integrity, origin authenticity, and

nonrepudiation of API requests. While alternatives exist, they
are insufficient in scenarios involving third parties requiring
nonrepudiation.

30.1 Motivation

Understanding the origin of API requests is crucial for

authentication. Three key requirements must be established:
1.
Origin:
Confirm the request comes from the claimed user and is
verifiable by credentials.
2.
Integrity:
Assurance that the request content has not been altered in
transit.
3.
Nonrepudiation:
Prevent the sender from denying they sent the request.

30.1.1 Origin

Establishing the request's origin focuses on verifying the

user's identity through proof from their registered credentials,
rather than physical identifiers.

30.1.2 Integrity

Integrity guarantees that the received request is unmodified

since sending. This requires mechanisms to ensure the data
remains intact during transmission.

30.1.3 Nonrepudiation

Nonrepudiation prevents the originator from denying their

involvement in the request. This necessitates asymmetric
credentials, where the user’s private key is not shared with
the API server.

30.2 Overview

Digital signatures are highlighted as a robust solution for

authentication, employing a pair of asymmetric credentials to
generate and verify signatures, ensuring the authenticity and
integrity of requests.

30.3 Implementation

The implementation of request authentication using digital

signatures occurs in several stages:

30.3.1 Credential Generation

Users generate a public-private key pair where the private

key remains confidential to maintain identity integrity.

30.3.2 Registration and Credential Exchange

Upon registration with the API, users provide their public

key to create a unique identifier without using traditional
authentication methods.

30.3.3 Generating and Verifying Raw Signatures

Digital signatures, created from the request payload using the

private key, are then verifiable using the corresponding
public key, ensuring integrity and authenticity.

30.3.4 Request Fingerprinting

Fingerprinting assembles essential components of a request,

capturing details such as HTTP method, URL, and
authorization headers, ensuring consistent signature
generation.

30.3.5 Including the Signature

Essential metadata must accompany the signature for

verification, including the key identifier, algorithm, and
headers used to generate the fingerprint.

30.3.6 Authenticating Requests

Authentication involves verifying the request's digest against
its content and utilizing the public key to validate the
provided signature.

30.3.7 Final API Definition

The API definitions include endpoints for user creation and

retrieval using the generated public keys, focusing on the
digital signature process for transactions.

30.4 Trade-offs

Choosing an authentication method involves trade-offs

concerning security, computational efficiency, and
implementation complexity. While digital signatures provide
high security, they may be overkill for less critical
applications where alternatives might be easier to implement.

30.5 Exercises

Questions are posed for reflection on the significance of

origin, integrity, and nonrepudiation in request
authentication.
Summary

Successful request authentication demands proof of origin,

integrity of the request, and means to prevent future
repudiation, emphasizing the importance of credentials for
identity validation. The process of signing involves creating
a fingerprint from key request attributes, ensuring reliability
in API communications.
Best Quotes from API Design Patterns
by J.J. Geewax with Page Numbers
View on Bookey Website and Generate Beautiful Quote Images

Chapter 1 | Quotes From Pages 6-64

1....once you’ve cracked the integration aspect, you
can write useful apps really easily, standing on the
shoulders of multiple giants.
[Link] lots of people read it, and follow its guidance, together
we might move the needle toward a more consistent and
less frustrating web API experience.
[Link] the real world, I learned how perfectly-optimized code is
not nearly as valuable as well-designed code.
[Link] should still expect to have to think, and think hard, but
with confidence that the result of that thinking can be an
API that is a joy to work with.
5.A well-designed API often feels obvious despite being the
result of huge amounts of toil.
Chapter 2 | Quotes From Pages 67-103
[Link] are interfaces specifically for computers with
 important properties to make it easy for
computers to use them.
[Link] open the door to composition, which allows us to
treat functionality like Lego building blocks, assembling
pieces together in novel ways to build things that are much
larger than the sum of their parts.
[Link] power of patterns... tends to be easier than learning
about pre-built complex things that follow a custom design
every time.
[Link] though this inconsistency might seem insignificant, it
turns out that issues like these are much more important
than they appear.
[Link] built using well-known, well-defined, clear, and
(hopefully) simple patterns will lead to APIs that are
predictable and easy to learn, which should lead to overall
'better' APIs.
Chapter 3 | Quotes From Pages 104-161
[Link] design patterns are sort of like adaptable
blueprints for designing and structuring APIs.
[Link] design patterns help minimize the need for large
structural changes.
[Link] an API, with and without design patterns, can
lead to vastly different outcomes in terms of flexibility and
ease of implementation.
[Link] starting with a pattern-driven approach, the API will
evolve gracefully as new functionality is needed.
Chapter 4 | Quotes From Pages 164-216
[Link] of this, it should seem obvious that it’s
important to choose great names (even if we don’t
always give our naming choices as much thought
as we should).
[Link] means we need to put an extraordinary amount of
thought and consideration into the names we choose for an
API.
[Link] expressive name clearly conveys the thing that it’s
naming.
[Link] should be expressive, but only to the extent that
each additional part of a name adds value to justify its
presence.
[Link] using the same name to represent the same thing and
different names to represent different things, we’re
allowing users of an API to build on what they’ve already
learned.
[Link], this underscores why descriptive names are
valuable and can help highlight differences in assumptions,
 particularly when coordinating between different teams.
Chapter 5 | Quotes From Pages 217-268
[Link] our focus away from actions and toward
resources allows us to more easily and more
quickly build our familiarity of an API by
leveraging simple patterns.
2.A key part of choosing the right resources is understanding
how they’ll fit together in the future.
[Link] resource layout of an API is probably easiest to
understand when we look at it visually as boxes connected
to one another by lines.
[Link] can often be tempting to create resources for even the
tiniest concept you might want to model in your API.
[Link] overly deep hierarchical relationships as they can be
difficult to comprehend and manage.
Chapter 6 | Quotes From Pages 269-343
[Link] this serialization process provides a huge
benefit, it’s not without its downsides. The biggest
one is that some information will be lost in
 translation due to the fact that every language acts
somewhat differently.
[Link] simply, it’s fundamentally insufficient to rely on the
data types provided by our programming language of
choice when thinking about those who will use a web API.
[Link] this extra context on data, we may end up stuck,
guessing about the actual intent of a client.
[Link] approach limits flexibility, but in the interest of
consistency and predictability, it’s typically the better
design choice.
[Link] it comes to bounds, our main focus is their size... It's
much safer to set upper and lower bounds with room for
growth over time.
[Link] proper structuring of data types within an API allows it
to be extensible and resilient against change, preparing it
for growth and future requirements.
Chapter 7 | Quotes From Pages 346-423
[Link] should be easy to use in the most
common scenarios.
[Link] obvious requirement of a good identifier is,
probably, that it must be truly unique.
[Link] should probably not change once they’re
assigned.
[Link] and easy to generate identifier options should have
predictable performance characteristics.
[Link]’s important that identifiers are readable, shareable, and
verifiable.
[Link] for information density will be a balancing act
with the other attributes that make good identifiers.
[Link] a resource by incorporating its type adds
significant value.
[Link] relationships are very useful and should be
used when appropriate.
[Link] characters can effectively distinguish between
valid and invalid identifiers.
[Link] are large, which is overkill for the most common
scenarios.
Chapter 8 | Quotes From Pages 424-483
[Link] of the characteristics of a good API is
predictability.
[Link] less a user has to learn about an API, the quicker they
can start using it to accomplish their own goals.
[Link] methods should do exactly what they say they’ll
do, and nothing more.
[Link] every standard method is required for each resource
type.
[Link] methods should (and likely will) get an API 90%
of the way there.
[Link] of the most important aspects of an API is its
transactional behavior, and one of the key aspects of that is
strong consistency.
Chapter 9 | Quotes From Pages 484-550
[Link] is quite a lot of value in providing the ability
for users of an API to retrieve only the pieces of a
 resource (or list of resources) that they’re truly
interested in.
[Link] they intend to replace the entire resource, they have the
standard replace method at their disposal. If they intend to
update only a single field, there should be a more
fine-grained mechanism by which they can express this
intent to update the resource.
[Link] goal of a standard get method is to be consistent across
resources, so introducing any variability that depends on
which resource you’re interacting with leads to surprises,
resulting ultimately in a worse-off API for consumers.
[Link] it comes time to determine what to update, we will
assign the input value to the resource’s value, which, in this
case, will be equivalent to "null", and have the desired
result of removing the key from the dictionary.
[Link] masks should not provide a mechanism to address
items in array fields by their position or index in that field.
Chapter 10 | Quotes From Pages 551-594
[Link] because we can perform an action with a
standard method doesn’t mean that we should
perform that action.
[Link] methods are nothing more than API calls that fall
outside the scope of a standard method...meaning they are
free to do whatever is best for the scenario.
[Link] goal of standard methods is to be a limited mechanism
to access and manipulate resource data.
[Link] methods should target a collection when multiple
resources from a single collection are involved, leaving the
resource-targeted custom methods for operations involving
just that single resource.
[Link]’s critical to be entirely certain that any new custom
method is not acting as duct tape to avoid admitting that the
resource layout is wrong.
Chapter 11 | Quotes From Pages 595-662
[Link] default behavior of using the same API
structure and asking users to 'just wait longer' is
 not a very elegant option.
[Link] it’s a minor or a major amount of work, one thing
is clear: relying on the same API design for both
consistently quick behavior and potentially very slow
behavior is unlikely to work very well.
[Link] goal of this design pattern is to answer this question.
[Link] problem is not unique to web APIs. In fact, it’s much
more common with work being executed locally in a
program.
[Link] behavior and make it easy to manage in our
programs.
[Link] most important thing to remember is that expiration
times of resources should not depend on the underlying
result types of the operation.
Chapter 12 | Quotes From Pages 663-704
[Link] the ability to handle asynchronous
execution is clearly very valuable; however, it still
requires that a client trigger the invocation
somewhere by calling the API method.
[Link] should probably define a standard for configurable jobs
that can store the various configuration parameters and be
rerun as needed, (potentially on a schedule).
[Link] splitting the work into two separate components, we lay
the groundwork for solving all three of the use cases
described in section 11.1.
[Link] of a complicated scheduling system that accepts
lots of parameters, we can simply request that a single API
method is called, with no parameters at all, on a specific
schedule.
[Link] it comes to execution resources, we certainly have an
alternative option to simply keep Operation resources
around forever as the reference of the output.
Chapter 13 | Quotes From Pages 707-744
[Link] other words, according to API design best
practices, the component is definitely best suited to
be a property, but it would be impractical to
follow those best practices in this case and would
end up making a worse experience for those using
the API.
[Link] a component will potentially become larger than all other
pieces of a resource combined, it may make sense to
separate that component from the resource.
[Link] there are pieces of a resource that have very different
access restrictions from the resource they nominally belong
to.
[Link] entire point of separating something into a
sub-resource is to isolate it in some way from the parent
resource.
[Link] means that the 'get' and 'update' methods we’d define
for a singleton sub-resource would be identical to those of a
regular resource.
[Link] a cascading deletion would be surprising or not fit with
the expectations of a typical consumer, this is often a good
sign that the singleton sub-resource pattern isn’t a great fit
for the use case.
Chapter 14 | Quotes From Pages 745-773
[Link] rarely live in a vacuum.
[Link] the general idea behind referencing resources is
quite simple, the details can be fairly complicated.
[Link]’s possible to have circular references between two
resources.
[Link] this might be inconvenient, it provides the most
consistent behavior to consumers with clear and simple
expectations: references should be checked.
[Link]’s usually best to use references alone and then rely on
something like GraphQL to stitch these various references
together.
Chapter 15 | Quotes From Pages 774-825
[Link] goal of this pattern is to outline a specific way
in which we can expose the rows in these join
 tables as separate resources that represent the
association between two resources in an API.
[Link] these many-to-many relationships have a standard
canonical representation in most relational databases, it’s
not always clear how we expose this concept in an API.
[Link] most powerful aspect of using an association resource
is the ability to store metadata about the relationship itself.
[Link] express this natural alignment of the association
resources, we can optionally alias a subcollection
underneath each of the resources being associated.
[Link] most resources, association resources tend to have a
very important uniqueness constraint that we must apply:
there should be only one association resource that
represents the two resources being associated.
Chapter 16 | Quotes From Pages 826-856
[Link]’ll explore an alternative pattern for modeling
many-to-many relationships that relies on custom
add and remove methods to associate (and
disassociate) two resources.
[Link] particular, we often have to handle situations where two
resources can both have many of one another, known as a
many-to-many relationship.
[Link], since we only ever store the simple fact that two
resources are associated, we won’t be able to store any
metadata about the relationship itself.
[Link] we’re going to use custom methods to add and
remove the association between the resources, we have to
consider one of the resources the managing resource...
[Link] exchange for this simplification, we make a few
trade-offs in the form of functional limitations.
[Link] scenarios where association resources are too
heavyweight... using add and remove custom methods can
be a simpler way to manage many-to-many relationships.
Chapter 17 | Quotes From Pages 857-896
[Link], in web APIs, should ideally be
focused on polymorphic resources and not
polymorphic methods, for the reasons discussed
earlier.
[Link] is, obviously, a very powerful tool in many
programming languages, so it stands to reason that
polymorphic resources are similarly quite valuable for web
APIs.
3.A good rule of thumb is to consider whether the resources
are all truly special types of the generic resource type.
[Link] our web API, our concern should be more about how we
intend the various standard methods to work and whether
those standard methods operate identically on all of these
resources or have some behavioral differences for the
different types.
[Link] resources have one important distinguishing
field: a type.
[Link], there may be others where resources might seem
 similar but still have some fundamental differences.
[Link] we go around changing types and breaking
assumptions like that, it often leads to confusing situations
for users and bugs in the API itself.
[Link]’s far safer to assume that things will change and will do
so in their own unique ways, not as a uniform group.
[Link] many times, it might be a perfect fit, there may be
others where resources might seem similar but still have
some fundamental differences.
Chapter 18 | Quotes From Pages 899-951
[Link] an ideal world, our hierarchical relationships
between resources are perfectly designed and
forever immutable. More importantly, in this
magical world, users of an API never make
mistakes or create resources in the wrong location.
And they certainly never realize far too late that
they’ve made a mistake.
[Link] make things more complicated, there may be scenarios
where users need to duplicate resources, potentially to
 other locations in the hierarchy. And while both of these
scenarios seem quite straightforward at a quick glance, like
most topics in API design, they lead us down a rabbit hole
full of questions that need to be answered.
[Link] goal of this pattern is to ensure that API consumers can
rename and copy resources throughout the resource
hierarchy in a safe, stable, and (mostly) simple manner.
[Link] many cases, copying resources can actually be a critical
piece of functionality. Moving resources, on the other
hand, often only becomes necessary as the result of a
mistake or poor resource layout.
[Link]’s important to note that while the complexity spelled out
in this chapter for the behavior of the move and copy
operations might be onerous and challenging to implement,
cutting corners here is far more likely to lead to nasty
consequences down the road.
[Link] point is that resources provided to the open internet are
often best effort and rarely come with a lifetime guarantee.
[Link] means that, while we might relocate the resource
 record itself, the data should remain untouched. For
example, renaming a File resource should change the home
of that resource, but the underlying bytes should not be
moved anywhere else.
[Link], the point is that some resources will make
sense to copy alongside the target while others simply
won’t. It’s a far less complicated technical problem and
instead will depend quite a lot on the intended behavior for
the API.
Chapter 19 | Quotes From Pages 952-1008
[Link] goal of these batch operations is to extend that
same principle of atomicity to methods performed
on multiple resources rather than just a single one.
[Link] an ID provided in the list would conflict with an
explicitly specified parent, the request should be rejected as
invalid.
[Link] we say a set of operations is atomic, we mean that
these operations are indivisible from one another.
[Link] need to take an imperative view of the delete operation
rather than a declarative one.
[Link] from batch operations should be in the same order
as the resources or requests were originally sent.
Chapter 20 | Quotes From Pages 1009-1042
[Link] purge method allows users to delete resources
without even being aware of the full extent of what
they’re deleting.
[Link] final issue to worry about is quite a bit trickier and one
that deserves at least a mention here: consistency.
[Link] default, the purge method acts as though we’re asking
for a preview only.
[Link] the world of APIs, this is not an uncommon occurrence.
[Link]’s generally a good idea to avoid supporting this
functionality in an API unless absolutely necessary.
Chapter 21 | Quotes From Pages 1043-1069
[Link] resources have always acted as single,
addressable, uniquely identifiable chunks of data
that we can bring into existence, operate on, read,
and then bring back out of existence when we’re
done with them, and they’ve served us well so far.
[Link]’s far more likely that we’ll ask for the average value of a
data point for the month rather than requesting to view a
specific single data point using a unique identifier.
[Link] write method is to allow data that is not addressable to
be added to a system. This means that the method by which
we read the data is very different from the way we would
read data added by the standard create method.
[Link] we’re using one of these systems for storing our
 analytical data, how exactly are we supposed to get data
into the API in the first place?
[Link] than resources, the write method deals with entries,
which are similar to resources, but are not addressable and,
in many cases, ephemeral.
Chapter 22 | Quotes From Pages 1070-1115
[Link] consumers to read their data in a single
large chunk becomes more and more
unreasonable.
[Link] term pagination comes from the idea that we want to
page through the data, consuming data records in chunks,
just like flipping through pages in a book.
[Link] accomplish this, our pagination pattern will rely on the
idea of a cursor, using opaque page tokens as a way of
expressing the loose equivalent of page numbers.
[Link] than expecting all of the data in a single response
interface, we’ll enter a back-and-forth sequence whereby
we request a small chunk of data at a time.
[Link], in many larger-scale systems, this simply won’t
be possible without paying a significant cost premium.
[Link] the consumer is able to discern the structure or meaning
of this token, then it’s part of the API surface and must be
treated as part of the API itself.
[Link] page tokens, we can guarantee strongly consistent
 pagination.
[Link]’s generally a good idea to set token expiration to be
relatively short given your use case.
[Link] this total count is relatively small, it’s an easy
statistic to show.
[Link] fundamental problem with this pattern is that it leaks
the implementation details to the API, so this API must
continue to support offsets and limits regardless of the
underlying storage system.
Chapter 23 | Quotes From Pages 1116-1160
[Link] filtering on standard list methods means
that users aren’t required to fetch all data in order
to find only those they’re interested in.
[Link] specifications should generally be strings adhering to
a specific syntax, akin to a SQL query, rather than a
structured interface to convey the same intent.
[Link] should not provide a way to compare items on a
resource based on their position or index in a repeated
field.
[Link] discovered during a filter evaluation should be
surfaced immediately rather than hidden or ignored.
[Link] basic comparisons are insufficient for users’ intentions,
filters should provide a set of documented functions that
can be interpreted and executed while filtering.
Chapter 24 | Quotes From Pages 1161-1224
[Link]’s consider the case where we have some
serialized data we want to load into an API, such
as a bunch of Message resources to be created
inside a ChatRoom resource...there’s one key
aspect of this plan that might turn out to be a
problem: the route the data is required to take.
[Link] of this, there’s a pretty strong case to be made for
having data flow directly between the API and a remote
storage system.
[Link] goal of this pattern is to bridge the gap between an API
service and an external storage system, avoiding the
middleman to shuffle data between the two.
[Link] this may seem like a tiny detail, it turns out that this
 single field leads us to quite a few interesting questions.
[Link] key takeaway from this section should be the critical
idea that exporting data is not the same as backing up data.
[Link] we learned in section 23.1, the goal of this pattern is to
bridge the gap between an API service and an external
storage system, avoiding the middleman to shuffle data
between the two.
[Link] we do the same with a ChatRoom resource, our
focus appears to have shifted away from the simple
shuffling and routing of data and into the world of backup
and restore functionality.
Chapter 25 | Quotes From Pages 1227-1297
[Link] software we build is rarely static. Instead, it
tends to change and evolve frequently over time as
new features are created and new functionality is
added.
[Link] primary goal of versioning is to provide users of an
API with the most functionality possible while causing
minimal inconvenience.
[Link] how to implement versioning in a web API will
vary with the expectations and profiles of those building
the API, as well as those using it on the other side.
[Link] decision is likely to be purely right or wrong; however,
designers must choose the best option based on what the
users of the API expect.
[Link] trade-offs we make on these topics will almost
certainly be our way of striking a balance between two
different ends of a spectrum.
[Link] APIs don’t make the choice of where on the
spectrum best suits their users (and instead just make it up
 on the fly), they tend to anger and frustrate users far more.
Chapter 26 | Quotes From Pages 1298-1345
[Link] many scenarios this permanent removal of
data... is a bit too extreme.
[Link]’d be wonderful if our deletions... could be partial or
soft... hidden from view... but... still recoverable.
[Link]’ll need a way to undelete resources just as easily as...
delete them.
[Link] deletion in general is a trade-off between permitting
users to remove specific information permanently... and
preventing them from shooting themselves in the foot.
[Link] leads to more complicated questions to answer... what
happens if we attempt to soft delete a resource that’s
already marked as deleted?
Chapter 27 | Quotes From Pages 1346-1382
[Link] a world where we cannot guarantee that all
requests and responses will complete their
journeys as intended, we will inevitably need to
retry requests as failures occur.
[Link] pattern explores the idea of providing a unique
identifier to each request that we want to ensure is serviced
once and only once.
[Link] returning an error stating that this request was
already handled is certainly sufficient, it’s not all that
useful in practical terms.
[Link] using this simple algorithm, whenever we see a request
ID that has already been serviced, we can double-check
that it really is a duplicate of the same request and not a
collision.
[Link] final API definition is quite simple for this pattern: just
adding a single field.
[Link] identifiers are generated by the API client and act
as a way to deduplicate individual requests seen by the API
service.
Chapter 28 | Quotes From Pages 1383-1410
[Link] the most straightforward APIs can be
somewhat confusing—after all, APIs are
complicated (otherwise there wouldn’t be a book
like this).
[Link] the end of the day, humans make mistakes whereas
computers just do exactly as they’re instructed to (even
when we might mean to instruct them differently).
[Link] specified as only needing validation should be a
bit like executing the work inside a transaction that’s
automatically rolled back and never committed.
[Link] most important thing in all of this is that any validation
request should result in a method that is completely safe
and idempotent.
[Link] providing a simple flag, these users can get some
amount of certainty in the face of a massive amount of
complexity that comes with all of the details present in
APIs.
Chapter 29 | Quotes From Pages 1411-1464
[Link] resources change over time, we typically
discard any changes that might have occurred in
the past.
[Link] goal of this pattern is to provide a framework that
enables storing multiple revisions for a single resource and
also allow other more complex functionality, such as
deleting revisions that aren’t necessary anymore or rolling
a resource back to a previous revision, effectively undoing
previous changes.
3.A resource revision is not a separate interface at all;
instead, it’s a concept brought about by simply adding two
new fields to an existing resource: a revision identifier and
a timestamp of when the snapshot was taken to create this
revision.
[Link] err is human, and while resource revisions are powerful
for letting us look back at the history of changes to a
resource, they also make it so that our mistakes live on
forever and simply cannot be forgotten.
[Link] critical thing to remember about this method is that it
 does not remove or alter the history of the resource. It
doesn’t take an old revision and move it to the front of the
line; instead, it creates an entirely new revision, copied
from an old one, and puts that duplicate at the top of the
pile.
Chapter 30 | Quotes From Pages 1465-1507
[Link]’s an inevitable fact of web APIs that some
requests will fail—hopefully, not the majority, but
some nonetheless.
[Link] point is that the error response wasn’t really caused by
the specific request made. On the contrary, the response
was due to things that were at best tangentially related to
the request and far more likely to have nothing to do with
the request.
[Link] accomplish this, we need to address two issues. First,
we must provide the clients with an algorithm to follow in
order to minimize the number of requests being retried
across the system.
4.A stampeding herd refers to a case where a bunch of
 remote clients all make the same request at the same time,
overwhelming the system on the receiving end.
[Link] the API service knows something the client does not, and
this information would lead to a specific time at which a
request could be retried successfully, the service should
have a mechanism to provide the client with an explicit
instruction of when to retry a request.
[Link] back-off generally will continue retrying a
request until the end of time or the request succeeds.
[Link] safest bet is to always rely on durations rather than a
specific time value, if possible.
Chapter 31 | Quotes From Pages 1508-1564
[Link] this pattern, we’ll explore how and why to use
public-private key exchange and digital signatures
to authenticate all incoming API requests.
[Link], the decision to honor a given request comes
down to a yes or no answer, but there are several different
requirements we need to consider to make this binary
decision.
[Link] refers to the certainty that the content of a request
as received is exactly as it was when sent.
[Link] refers to the idea that once we’ve verified
the origin of a request, that origin can’t then deny that they
were the origin.
[Link] credential used to sign requests is only ever in the
hands of the user and isn’t shared with the API server.
6.A digital signature is nothing more than a chunk of bytes,
but these bytes represent a value that, beyond a reasonable
doubt, can only be generated and verified using a special
pair of credentials.
[Link] determine what to put into the payload parameter when
generating or verifying a digital signature is a lot more
complicated than it sounds.
[Link] digital signatures for request authentication, meeting
all three of the key criteria makes these mechanisms
notably attractive.
API Design Patterns Questions
View on Bookey Website

Chapter 1 | API Design Patterns| Q&A

[Link]
What personal experience led you to explore API design?
Answer:In the summer of 2019, I got into drumming
and spent time programming my electronic drum kit
with MIDI commands, which shifted to focusing on
audio/visual needs during the COVID-19 pandemic
for my local church. This required me to learn
various protocols and create integration code,
leading to a balance of frustration and
empowerment in integrating different technologies.

[Link]
What emotions do developers experience when
interacting with new web APIs?
Answer:Developers often experience a mix of excitement,
bewilderment, annoyance, acceptance, and eventual uneasy
peace when learning a new web API. Understanding how a
powerful API works can make one feel like a conductor of an
orchestra, despite the inconsistencies that can exist between
the components.

[Link]
Why is API design considered more a matter of opinion
than mathematics?
Answer:API design is often less about rigid mathematical or
scientific principles and more about aesthetics and user
experience, where different developers can hold varying
opinions on what constitutes a 'well-designed' API.

[Link]
How does the author perceive the value of the book 'API
Design Patterns'?
Answer:The author views the book as a resource to help
provide greater consistency in API design across various
projects, encouraging users to see it as more than the sum of
its parts and as a potential foundation for a better API
experience.

[Link]
What does it mean for software, specifically web APIs, to
be 'well-designed'?
Answer:A well-designed web API provides an intuitive and
user-friendly experience, ensuring that the API structure and
functionality meet user needs effectively without
unnecessary complexity.

[Link]
How does the author suggest one should use the
guidelines provided in the book?
Answer:The guidelines should be used as battle-tested
suggestions with logical explanations, allowing API
designers to make informed decisions, whether to adopt or
adapt them based on their specific context.

[Link]
What is the goal of the API Design Patterns book?
Answer:The book aims to provide a collection of flexible,
reusable design patterns for building web APIs, focusing on
general design principles and practical solutions for common
API challenges.

[Link]
What are the main topics covered in the book's chapters?
Answer:The book covers general API design principles,
specific design patterns, naming conventions, resource
relationships, interacting with collections of resources, and
ensuring API safety and security.

[Link]
Why is it important to have a consistent approach across
multiple areas of API design?
Answer:A consistent approach across various areas of API
design helps avoid fragmentation, ensures easier
maintenance, and leads to a better user experience by
providing predictability in how different APIs behave.

[Link]
What does 'standing on the shoulders of giants' mean in
the context of API design?
Answer:This phrase indicates that by understanding and
integrating existing designs and patterns from established
systems, developers can create more effective and innovative
APIs, leveraging the knowledge and efforts of previous
teams.
[Link]
What experiences does the author share that connect to
the broader themes of API design?
Answer:The author's experiences with personal integration
projects and supporting church activities during the pandemic
exemplify the real-world challenges and satisfactions of
working with APIs, highlighting the emotional journey from
frustration to empowerment.

[Link]
How does the author suggest handling the 'incidental
complexity' in API design?
Answer:The author emphasizes that while API design is
complex, understanding and applying the book's guidelines
can help reduce unnecessary complexity, allowing
developers to focus on uniquely valuable aspects of their
APIs.

[Link]
What underlying message about API design does the
author hope to convey with this book?
Answer:The underlying message is that well-designed APIs
enhance user experiences significantly, and while the process
might be challenging, the ultimate outcome can lead to APIs
that users appreciate, even if they don't always explicitly
express thanks.

[Link]
How can readers engage with the content and community
surrounding 'API Design Patterns'?
Answer:Readers can access a private web forum provided by
Manning Publications for discussions about the book, ask
technical questions, and engage in meaningful dialogue with
the author and other readers.

[Link]
What does the author hope will result from widespread
adoption of the book's guidelines?
Answer:The author hopes that if many developers adopt the
guidelines, there will be a collective movement towards a
more consistent and less frustrating web API experience.
Chapter 2 | 1 Introduction to APIs| Q&A
[Link]
What are web APIs and how do they differ from
traditional libraries?
Answer:Web APIs define ways for computer
systems to interact over a network, allowing remote
use by different users. Unlike traditional libraries
where users have local copies and control, web APIs
are controlled by builders, who can enforce changes
directly on users without their consent.

[Link]
Why do APIs matter in software development?
Answer:APIs matter because they enable automation,
allowing programs to function faster and in more complex
ways. They provide computer-friendly interactions devoid of
visual complexity, making system changes easier without
needing to retrain the computer.

[Link]
What is resource orientation in APIs?
Answer:Resource orientation focuses on defining APIs based
on 'resources'—the key concepts managed by the
API—rather than purely action-oriented calls. This approach
standardizes methods to interact with resources, simplifying
the learning curve for users.

[Link]
What makes an API 'good'?
Answer:A good API must be operational (functioning as
intended), expressive (allowing clear user intent), simple
(easy to use without unnecessary complexity), and
predictable (following consistent patterns that reduce
surprises for users).

[Link]
How do resource-oriented APIs improve usability?
Answer:Resource-oriented APIs improve usability by
leveraging a set of standard methods related to resources,
making it easier for users to understand and remember how
to interact with the API. It simplifies learning new resources
by applying known principles to them.

[Link]
What operational aspects are important for an effective
API?
Answer:An effective API must perform its primary function
accurately and efficiently, with consideration to operational
requirements such as latency and accuracy to meet user
expectations.

[Link]
Why is expressiveness important in API design?
Answer:Expressiveness ensures that users can clearly convey
their requests to the API. If an API supports functionality
without an expressive way to access it, users may have to
resort to workarounds, complicating the interaction
unnecessarily.

[Link]
What does simplicity mean in the context of APIs?
Answer:Simplicity in APIs means exposing the desired
functionality in the most straightforward way possible. This
includes avoiding overly complex configurations or reducing
the number of methods unnecessarily, while still being
functional.

[Link]
How do predictability and consistency enhance API
usability?
Answer:Predictability ensures that users can make educated
guesses about how to interact with the API based on previous
experiences. Consistency in naming conventions and method
structures leads to a smoother learning process, allowing
users to apply their knowledge across different API calls.

[Link]
What strategy should one follow to design APIs that fit
together well?
Answer:One strategy is resource orientation, which
emphasizes the use of standardized methods and a clear
resource-based structure. This approach allows APIs to
interconnect as reliably as building blocks do, fostering an
ecosystem of reusable and clear functionalities.
Chapter 3 | 2 Introduction to API design patterns|
Q&A
[Link]
What is an API design pattern?
Answer:An API design pattern is essentially a
software design pattern specifically applied to APIs.
It serves as a template or blueprint that outlines how
components should interact with one another within
an API, facilitating the design and structuring of
APIs effectively.

[Link]
Why are API design patterns important?
Answer:API design patterns are crucial because APIs are
rigid, meaning changes to them can easily break existing
implementations. Using established design patterns helps
minimize the need for large structural changes, allowing for
more efficient iteration and improvement in API design.

[Link]
How does the analogy of building a shed help understand
design patterns?
Answer:The shed-building analogy illustrates that just like
there are multiple ways to construct a shed, ranging from
buying a pre-built shed to building one from scratch, in
software design, there are varying options for creating
solutions from pre-built libraries to fully custom systems.
Design patterns represent a middle ground where we can mix
and match established blueprints to build software
efficiently.

[Link]
What are the components of an API design pattern?
Answer:Components of an API design pattern typically
include a name and synopsis for identification, motivation
that explains the problem the pattern addresses, an overview
that outlines the solution, implementation details that
describe how to realize the pattern in code, and trade-offs
that highlight potential limitations or sacrifices necessary
when adopting the pattern.

[Link]
Can you explain the pagination pattern mentioned in the
context of APIs?
Answer:The pagination pattern is used to manage large sets
of data by breaking them down into smaller, manageable
chunks. Instead of returning an entire dataset in one response
(which could be cumbersome and inefficient), it allows
clients to request data page by page, enhancing performance
and usability.

[Link]
What might happen if we don’t use a design pattern from
the start?
Answer:If we don’t employ a design pattern initially, we may
end up making changes later that could break existing
implementations, leading to compatibility issues. For
instance, changing a simple API response structure to
accommodate new requirements can disrupt current users'
applications.

[Link]
What is the importance of the motivation section in an
API design pattern?
Answer:The motivation section defines the problem the
design pattern addresses, aiding in understanding why the
pattern is necessary. It often includes user-centric objectives
and potential edge cases, providing context for why this
solution exists and how it effectively addresses specific
challenges in API design.
[Link]
What does the implementation section of an API design
pattern entail?
Answer:The implementation section outlines how to put the
design pattern into practice. It details the structure of API
requests and responses and may include code examples that
demonstrate how to implement various aspects of the pattern
in a programming language.

[Link]
How do API design patterns facilitate iterative
development?
Answer:By providing proven templates and structures, API
design patterns allow developers to build on existing
frameworks without starting from scratch. This encourages
iterative development, as teams can enhance their APIs
gradually without risking breaking existing functionality.

[Link]
What does the 'trade-offs' component of a design pattern
discuss?
Answer:The trade-offs component evaluates the limitations
or sacrifices involved in using a design pattern. It may
address challenges such as increased complexity, reduced
flexibility, or potential functional limitations that could arise
when implementing the pattern in a specific context.
Chapter 4 | 3 Naming| Q&A
[Link]
Why is choosing good names in APIs more important
than in traditional programming?
Answer:In API design, names are part of the public
interface that users will interact with directly.
Unlike traditional compiled code where names
disappear during compilation, API names are visible
to all users, making it essential to choose them
thoughtfully to ensure clarity and prevent confusion.

[Link]
What are some characteristics that make a name 'good' in
an API?
Answer:Good names in APIs should be expressive (clearly
convey their purpose), simple (not overly complex), and
predictable (maintain a consistent naming pattern that users
can rely on).

[Link]
How does context influence the meaning of names in
APIs?
Answer:Context can significantly shape how a name is
understood. For instance, the term 'record' in an audio API
might mean one thing, while in a library API, it could imply
something entirely different. Thus, choosing contextually
relevant names is crucial.

[Link]
What should you do when faced with ambiguous names
that could refer to different concepts?
Answer:If a name could refer to multiple concepts, it's
important to choose more specific names that differentiate
their usage, like using 'messaging_topic' instead of just 'topic'
to avoid confusion.

[Link]
Why must we be careful with pluralization in API names?
Answer:Pluralization can be tricky because the plural form
may not follow simple rules. For example, 'Foot' becomes
'Feet,' and 'Person' could be 'People' or 'Persons.' It's essential
to choose a consistent pattern and apply it correctly.

[Link]
What can happen if you change names in an API later
on?
Answer:Changing names in an API can lead to significant
issues because users of the API may have already integrated
those names into their systems. This could result in
confusion, broken functionality, and require extensive
updates to user projects.

[Link]
What are some potential consequences of poor naming
choices in APIs?
Answer:Poor naming can lead to user misunderstanding,
code that is hard to maintain, and errors in API usage, such
as confusion over data types and functions. This may have
serious real-world implications, as illustrated by the NASA
Mars Climate Orbiter failure.

[Link]
What are 'smells' in API naming?
Answer:Names that use prepositions like 'with' or 'for' can
indicate deeper design problems within the API. They often
hint that there is not a clear way to represent relationships or
that the API design may be overly complicated.

[Link]
How important are data types and units in API names?
Answer:Including data types and units in names can help
clarify their meaning and avoid confusion. For instance,
specifying 'sizeBytes' instead of just 'size' makes it clear what
unit the size is measured in, reducing the chance of
misunderstandings.

[Link]
What are some guidelines to follow when naming things
in an API?
Answer:Some guidelines include using American English for
maximum interoperability, sticking to consistent naming
conventions (like case style), avoiding reserved keywords,
and ensuring that the meaning of names is clear through
context and specific naming.
Chapter 5 | 4 Resource scope and hierarchy| Q&A
[Link]
What is resource layout in the context of API design?
Answer:Resource layout refers to the arrangement
of resources within an API, including how they are
defined and how they relate to one another through
various fields. It is critical to understand resource
layout to create intuitive and efficient API
interactions.

[Link]
Why is it important to consider the relationships between
resources when designing an API?
Answer:Considering relationships is crucial because the way
resources connect can impact the API's functionality and
performance. A well-defined relationship can improve
navigation and data retrieval, while poorly thought-out
relationships can lead to performance degradation and
complexity.

[Link]
What are the different types of relationships that can
exist between resources?
Answer:The types of relationships include reference
relationships (one resource points to another), many-to-many
relationships (one resource can relate to multiple instances of
another), self-reference relationships (a resource points to
itself), and hierarchical relationships (where resources point
to one another in a parent-child structure).

[Link]
What is an anti-pattern in resource layout, and can you
give an example?
Answer:An anti-pattern is a common tactic or approach that
leads to ineffective or problematic outcomes. For example,
creating resources for every minor concept (like individual
points within a shape) leads to an unnecessarily complex API
design, whereas it might be better to treat those concepts as
data types within a main resource.

[Link]
How do hierarchical relationships differ from other types
of relationships?
Answer:Hierarchical relationships involve a parent-child
structure where actions on the parent resource (like deletion)
cascade to the child resources. This contrasts with simple
reference relationships, where one resource points to another
without implying ownership or cascading effects.

[Link]
What should you consider when deciding whether to use a
reference or in-line data?
Answer:Consider the frequency of data access and the size of
the referenced data. If the referenced data is small and often
needed, in-lining may reduce API calls. However, if it is
large or infrequently accessed, keeping it as a reference can
help optimize performance.

[Link]
What is a key guideline for maintaining manageable
hierarchies in API design?
Answer:Avoid overly deep hierarchies as they can complicate
data navigation and management. Instead, focus on
maintaining a shallow hierarchy that captures essential
relationships without unnecessary complexity.

[Link]
How can entity relationship diagrams aid in
understanding resource layout?
Answer:Entity relationship diagrams visually represent
resources and their relationships, helping designers see how
resources interconnect and identify potential issues or
improvements in the layout.

[Link]
What considerations should be made regarding the
performance implications of relationships in APIs?
Answer:It's necessary to evaluate the long-term costs
associated with relationships, as excessive interconnections
can degrade performance. Aim for relationships that are
fundamental to the API's purpose while avoiding accidental
or unnecessary connections.

[Link]
Can you summarize the importance of resource layout
and relationships in API design?
Answer:Resource layout and relationships are essential for
creating clear, efficient, and scalable APIs. They determine
how resources interact, affect usability, and can either
enhance or hinder performance based on how well they are
structured.
Chapter 6 | 5 Data types and defaults| Q&A
[Link]
Why is it important to pay attention to data types when
designing APIs?
Answer:Data types dictate how a programming
language interacts with a chunk of data, affecting
operations and outcomes. They are crucial for
ensuring that APIs can communicate consistently
across different programming languages because
APIs should allow anyone from any language to
interact with the service.

[Link]
What is the difference between a missing value and a null
value in the context of APIs?
Answer:A missing value means the key for that value isn't
present at all, while a null value indicates that the key is
present but explicitly set to a non-value. For instance, in a
JSON object, {'name': 'Apple'} has a present key and value,
{'name': null} has a present key with a null value, while
{'color': 'red'} is entirely absent.

[Link]
How should APIs handle the serialization of different
data types?
Answer:APIs should define their data types based on the
chosen serialization format, like JSON. This consideration is
to ensure that the transmitted data retains its intended
structure and meaning when sent to different programming
languages, minimizing loss of information during
serialization.

[Link]
When is it appropriate to use Boolean flags in an API?
Answer:Boolean flags are best used for binary decisions, like
permitting or disallowing chat bots in a chat room. However,
it is important to consider defaults when naming flags to
ensure clarity—using positive terms like 'allowChatbots' can
help reduce confusion.

[Link]
Why should enumerations generally be avoided in API
design?
Answer:Enumerations can lead to confusion, particularly
when their numeric representations are unclear or when new
values are added without client-side updates. Using strings
for values instead provides better flexibility and clarity for
API users.

[Link]
What considerations should API developers keep in mind
regarding lists?
Answer:Lists should be treated as atomic collections where
whole lists can be replaced instead of individual items
modified piecemeal. This ensures consistency and avoids
complications related to order and multiple modifying
operations.

[Link]
In what situations should numeric values be serialized as
strings instead of numbers?
Answer:Numeric values exceeding 32 or 64 bits, or those
prone to floating-point precision errors, should be serialized
as strings to prevent issues with different languages not
handling such numbers uniformly.

[Link]
What is the recommended approach if an API expects
potentially large lists or maps?
Answer:APIs should define upper limits for the number of
items allowed in lists or maps and reject any inputs that
exceed these bounds, maintaining predictability and avoiding
unexpected behavior.

[Link]
How can APIs ensure consistency with string data types?
Answer:APIs should standardize on a single encoding
format, typically UTF-8, for all string content, and normalize
strings to avoid issues with different byte representations of
semantically identical values.

[Link]
What are the implications of using large or variable-sized
values in map fields?
Answer:Maps should set boundaries for both key and value
sizes to manage expectations and prevent performance issues.
Not setting limits can lead to unpredictable API behavior as
users may store excessive amounts in a single map.
Chapter 7 | 6 Resource identification| Q&A
[Link]
What is an identifier in the context of APIs?
Answer:An identifier allows us to uniquely address
and refer to individual resources in an API. It
typically consists of a string or integer that points
specifically to one resource within a larger
collection.

[Link]
What attributes make an identifier good?
Answer:Good identifiers should be easy to use, truly unique,
permanent, fast and easy to generate, unpredictable, readable
and shareable, and informationally dense.

[Link]
Why is uniqueness important for identifiers?
Answer:Uniqueness is essential because an identifier's
primary function is to distinguish a single resource among
many. If identifiers aren't unique, it would lead to confusion
and errors when accessing resources.
[Link]
Why should identifiers be permanent?
Answer:Identifiers must be permanent to ensure consistency.
Changing identifiers can lead to ambiguity and errors,
particularly when users reference resources that have
identifiers that have been reassigned.

[Link]
What does it mean for an identifier to be fast and easy to
generate?
Answer:Generating identifiers should be efficient and not
resource-intensive, ensuring that the system remains
responsive even as the number of identifiers grows or as
additional identifiers are needed.

[Link]
Why is unpredictability a critical attribute in identifiers?
Answer:Unpredictable identifiers are crucial for security;
predictable patterns can be exploited by attackers, making it
easier for them to guess or access resources that might be
unprotected.

[Link]
How should identifiers be shared and communicated?
Answer:Identifiers should be readable and shareable,
avoiding characters that could be easily confused or
miscommunicated. This eases communication, especially in
non-digital mediums like phone calls or written notes.

[Link]
What is the role of a checksum in an identifier?
Answer:A checksum allows verification of the integrity of an
identifier, helping to distinguish between a valid identifier
that points to nothing (missing) and an invalid identifier that
has a typographical error.

[Link]
Why might one prefer using Crockford's Base32 for
identifiers?
Answer:Crockford's Base32 is preferable because it balances
readability, prevents confusion between characters (like 1, I,
and l), offers high information density, and is suitable for
error-checking with its checksum system.

[Link]
How can the size of identifiers impact their usability?
Answer:Choosing an appropriate size for identifiers helps
maintain efficiency in database storage, facilitates quick
lookups, and ensures that the identifiers are not too
cumbersome for users to manage and share.

[Link]
What considerations should be made when implementing
identifiers for hierarchical resources?
Answer:When designing identifiers for hierarchical
resources, it's important to reflect the ownership and
relationship between resources correctly while ensuring
identifiers remain stable and do not change inappropriately.

[Link]
How can one ensure that identifiers do not collide during
generation?
Answer:To avoid collisions, implement a system for
checking existing identifiers before assigning a new one,
maintain a sufficiently large key space, and utilize
cryptographic methods for generation.

[Link]
What are some typical uses of UUIDs in API design?
Answer:UUIDs are commonly used for generating unique
identifiers that need to be globally unique across systems,
thanks to their large key space, which reduces the chance of
duplicates.

[Link]
Why might an API designer choose to use
Base32-encoded UUIDs instead of plain UUIDs?
Answer:Base32-encoded UUIDs are more readable, easier to
share without confusion, and can include a checksum, which
helps verify the integrity of the identifier.
Chapter 8 | 7 Standard methods| Q&A
[Link]
What is the significance of having a predictable API?
Answer:Having a predictable API allows users to
leverage their existing knowledge to quickly
understand and use the API. Predictability is vital
for reducing the learning curve and increasing user
efficiency in achieving their goals.

[Link]
What are the standard methods commonly used in APIs?
Answer:The standard methods (actions) typically used in
APIs are Get, List, Create, Update, Delete, and Replace.
These methods provide a consistent set of actions that can be
performed on resources.

[Link]
Why is it essential for standard methods to be
idempotent?
Answer:Idempotence ensures that making the same request
multiple times produces the same result. This property is
crucial to minimize unexpected behaviors and side effects,
which could lead to data corruption or loss when the same
operation is repeated.

[Link]
What is the 'Replace' method, and how does it differ from
the 'Update' method?
Answer:The 'Replace' method is designed to substitute an
entire resource with new data, ensuring that any fields not
specified in the request are removed. In contrast, the 'Update'
method modifies only the fields explicitly mentioned in the
request, allowing partial updates.

[Link]
What are the potential drawbacks of using standard
methods in API design?
Answer:While standard methods provide consistency and
ease of use, there may be scenarios where their strict
adherence doesn't align with the unique requirements of an
API, leading to limitations that could be addressed with
custom methods.

[Link]
Why should APIs avoid including result counts and
custom sorting in list methods?
Answer:Including result counts can add complexity and
overhead, especially as the number of records grows, leading
to performance issues. Custom sorting complicates data
handling and can strain server resources as datasets increase.
Instead, the focus should be on retrieving data efficiently.

[Link]
How should an API handle access control when listing
resources?
Answer:When listing resources, the API should only return
the items that the requester has access to, ensuring that users
see a tailored view of available data without exposing
secured information.

[Link]
What are some suggested guidelines for when to
implement each standard method?
Answer:Each standard method should exist on a resource
unless there is a valid reason not to support it, which should
be well-documented. It allows the API to maintain a general
rule of consistency while accommodating exceptions.

[Link]
Can the standard methods adapt to real-world scenarios
where certain resources may not behave traditionally?
Answer:Yes, while standard methods serve as a guideline,
API designs can adapt to context-specific scenarios—like
immutable resources opting out of update methods—by
returning appropriate HTTP status codes like 405 Method
Not Allowed for unsupported operations.
[Link]
How does avoiding side effects improve standard methods
in APIs?
Answer:By avoiding side effects, standard methods can
guarantee reliable outcomes, preventing unexpected behavior
that may complicate user interactions and lead to confusion
or errors in the system.

[Link]
What steps can API designers take to maintain strong
consistency when creating a resource?
Answer:Designers should ensure that after a resource is
created, it should be immediately available for all standard
operations and properly reflected across all endpoints to
uphold transaction reliability.
Chapter 9 | 8 Partial updates and retrievals| Q&A
[Link]
What is the primary motivation behind implementing
partial updates and retrievals in APIs?
Answer:The primary motivation is to minimize
unnecessary data transfer and allow for fine-grained
modification of API resources, especially in
scenarios where resource size or client hardware
constraints demand such functionality.

[Link]
Why might controlling the amount of information
returned from an API be important for IoT devices?
Answer:Controlling the amount of information is critical for
IoT devices because these devices often have limited
memory, processing power, and bandwidth, making it
necessary to retrieve only the data that is of immediate
interest.

[Link]
What issues arise when two clients attempt to update the
same resource simultaneously without detailed field-level
updates?
Answer:Simultaneous updates can lead to data loss or
inconsistency. For example, if one client updates a field
while another client is also making changes without proper
consistency checks, one client's changes may be overwritten,
leading to a situation where only the final change is
effectively saved.

[Link]
How do field masks facilitate more specific API
interactions?
Answer:Field masks enable API consumers to specify
exactly which fields they want to retrieve or update, thus
allowing users to express their intent more clearly and
efficiently without modifying or retrieving the entire
resource.

[Link]
What is the default behavior of a standard GET method
when field masks are not specified?
Answer:When field masks are not specified in a standard
GET request, the default behavior is to return the complete
list of fields available on the resource.

[Link]
How should APIs handle invalid field specifications in
requests?
Answer:APIs should treat invalid field specifications as if
they exist but have a value of null, ensuring that such fields
do not lead to errors or exceptions during processing.

[Link]
What is the significance of nested fields and maps in
comprehensive API design?
Answer:The ability to address nested fields and maps allows
for more granular updates and retrievals, accommodating
complex data structures typically found in modern
applications.

[Link]
Why shouldn't APIs support addressing items in repeated
fields by their index?
Answer:Addressing items by index can lead to ambiguity and
instability, as the index may change with the addition or
deletion of items, making it hard to guarantee that the
intended item is always targeted.

[Link]
What mechanism can be used to remove a key from a
dynamic data structure in an API?
Answer:To remove a key from a dynamic data structure, the
API should allow sending a request that specifies the field to
be removed, potentially by omitting its value entirely from
the request.

[Link]
What alternatives exist to using field masks for API
updates, and what is a significant limitation of those
alternatives?
Answer:Alternatives like JSON Patch and JSON Merge
Patch provide more control over resource modification, but
they can introduce complexity when dealing with dynamic
data structures, especially regarding distinguishing between
setting a field to null and removing it.

[Link]
What condition should be met for an API to ensure
consistent support for partial retrievals across different
resources?
Answer:If an API requires partial retrieval for any resource,
it should implement this functionality uniformly across all
resources to avoid surprising users and ensure a consistent
user experience.
Chapter 10 | 9 Custom methods| Q&A
[Link]
Why are custom methods necessary in API design?
Answer:Custom methods are necessary when the
standard HTTP methods (GET, POST, PUT, etc.) do
not adequately express specific actions required for
certain operations, especially those with unique side
effects or workflows. For instance, sending an email
or applying a complex data transformation often
cannot be cleanly represented by standard methods,
leading to confusing, cluttered APIs.

[Link]
What problems arise from trying to use standard
methods for operations that require side effects?
Answer:Using standard methods for operations with side
effects often leads to a convoluted API behavior where a
single method might perform multiple actions, making the
API unpredictable and harder to use. For example, attempting
to send an email by using an 'update' method to change its
state does not clearly communicate the intended action to the
API user, resulting in confusion.

[Link]
What guidance does the chapter provide regarding when
to create custom methods?
Answer:The chapter suggests considering custom methods
when the desired action cannot be expressed through
standard methods without causing confusion or violating
their principles, particularly regarding side effects. If an
operation requires transitioning states or involves interactions
with external systems, a custom method should be created to
explicitly handle that action.

[Link]
Can you explain the difference between resource-targeted
and collection-targeted custom methods with examples?
Answer:Resource-targeted custom methods operate on a
single resource (e.g., sending an email would be a custom
method like POST /users/1/emails/2:send).
Collection-targeted custom methods act on multiple
resources in a collection (e.g., deleting multiple emails might
use a method like POST /users/1/emails:delete), making it
clearer when the operation affects more than one item.

[Link]
What is a stateless custom method and when might it be
used?
Answer:A stateless custom method does not rely on any
stored data and does not maintain state across requests. This
is particularly useful in cases where data privacy regulations
prevent storing user data. For example, translating text on the
fly without saving it requires a stateless API method, as
shown in the example with a translation API that accepts
input and immediately returns a translation without storing
the text.

[Link]
What are the trade-offs associated with using custom
methods in API design?
Answer:Custom methods can introduce greater flexibility
into an API but may also contravene RESTful principles if
overused. They should provide clear, predictable interactions
without obscuring the underlying resource structure. Poorly
designed APIs often over-rely on custom methods for simple
operations better suited to standard ones, which can hide
design flaws and complicate maintenance.

[Link]
What practices should be followed when designing
custom methods?
Answer:Custom methods should typically use the POST
HTTP verb, employ clear naming conventions, and utilize
the colon (:) as a separator between resource targets and
actions. It's important to document side effects thoroughly
and to ensure consistency across custom methods within the
API. Additionally, they should be used judiciously, targeting
collections when dealing with multiple resources.

[Link]
How does the chapter suggest addressing the potential
misuse of custom methods?
Answer:To mitigate misuse, the chapter emphasizes the
importance of assessing whether a custom method is
genuinely fulfilling a unique need or merely compensating
for poor resource design. Proper resource layout should
ideally allow for standard methods to cover most actions,
reserving custom methods for scenarios where standard
methods are inadequate.
Chapter 11 | 10 Long-running operations| Q&A
[Link]
Why is it important to use long-running operations
(LROs) in API design?
Answer:Using LROs allows APIs to handle
operations that require significant time to complete
without blocking the client. This asynchronous
behavior enhances user experience by permitting
immediate feedback while the API performs the
work in the background.

[Link]
What should be included in the metadata of an LRO and
why?
Answer:The metadata should include fields for tracking
progress, such as the percentage complete, the time started,
and the estimated time remaining. This provides users with
real-time updates on the operation's status and helps manage
expectations.

[Link]
What are the key differences between LROs and
programming language promises or futures?
Answer:Unlike programming promises that are ephemeral
and exist only during execution, LROs are persistent API
resources that can outlive the request that created them,
residing on the server and providing feedback about
background operations.

[Link]
How can users cancel a running LRO, and what should
happen afterward?
Answer:Users can invoke a CancelOperation method to
request termination of the LRO. After cancellation, the API
should ensure the operation state reflects that it's completed
and should also clean up intermediate products if possible.

[Link]
What is the role of polling in managing LROs, and what
is its downside?
Answer:Polling allows clients to check the status of an LRO
periodically until it completes. However, its downside is
increased network traffic and the potential for wasted
resources if updates take longer than expected.

[Link]
What is the significance of having a top-level collection of
LROs in API design?
Answer:Having a centralized top-level collection makes it
easier to manage and query all ongoing operations in one
place, facilitating monitoring and interaction without needing
to know the specific resource being operated upon.

[Link]
How does a client interact with the LRO to check
progress or obtain results?
Answer:Clients can interact with LROs using methods like
GetOperation to query the LRO for its current state or use a
custom method like WaitOperation to block until the
operation completes, making it easier to retrieve results.

[Link]
What should be considered about the expiration of
LROs?
Answer:LROs should have a defined expiration policy, such
as automatic deletion after 30 days, to avoid cluttering the
system with obsolete records, thus ensuring efficient resource
management.

[Link]
How can error handling be effectively managed in LROs?
Answer:Error handling in LROs should provide an
OperationError structure that includes an error code,
message, and additional details, separating API errors from
those stemming from the underlying operation.

[Link]
What best practices should be followed when
implementing pause and resume functionality for LROs?
Answer:When implementing pause and resume, it is crucial
to manage this functionality through relevant metadata,
ensuring operations can be paused without compromising
their integrity or user expectations about completing the task.
Chapter 12 | 11 Rerunnable jobs| Q&A
[Link]
What are rerunnable jobs and why are they important in
API design?
Answer:Rerunnable jobs are a mechanism that
allows specific configurable tasks to be defined,
stored, and executed multiple times without
requiring a client to provide all configuration details
repeatedly. This is important because it enhances
efficiency, simplifies permissions management, and
allows for better scheduling of tasks directly within
the API.

[Link]
How do rerunnable jobs resolve the challenges of
permissions in API operations?
Answer:Rerunnable jobs differentiate between the
permissions needed to execute a task and those needed to
configure it. This means that users can be allowed to run
preconfigured jobs without having the ability to change their
parameters, which aligns with role-specific responsibilities in
complex systems.

[Link]
Can you illustrate how a rerunnable job might evolve
from a traditional on-demand API method?
Answer:Certainly! Suppose there’s an API method that
triggers a backup of a chat room. Initially, it may require the
user to provide all configuration parameters each time it’s
called. By transitioning to a rerunnable job, we create a
BackupChatRoomJob resource that holds these parameters.
Users can create this job once and then call a simple 'run'
method whenever they want to execute that backup, thus
streamlining the process.

[Link]
What is the significance of distinct execution resources in
the context of rerunnable jobs?
Answer:Execution resources hold the results of the tasks
performed by the jobs. They allow users to access data from
previously run jobs, provide a clear record of outcomes, and
ensure these outputs are managed under their own persistence
policies, separate from the job definitions and configurations.
This avoids confusion and promotes better data integrity.

[Link]
How does the design of rerunnable jobs support
scheduling within APIs?
Answer:Rerunnable jobs can be designed to support
scheduling directly by allowing the API to invoke the
execution of jobs at predetermined intervals. This removes
the dependency on external scheduling systems and
simplifies the architecture, making the API more robust and
easier to use.

[Link]
What are the trade-offs of implementing rerunnable jobs
explained in this chapter?
Answer:While rerunnable jobs effectively solve issues like
parameter complexity and permissions, they are one of many
potential solutions. Alternatives might include more complex
permission systems that check parameters or keeping LROs
indefinitely. The choice of rerunnable jobs means embracing
simplicity at the risk of developing more generic permission
models that could limit granularity.

[Link]
In what ways do the examples provided in the chapter
enhance understanding of rerunnable jobs?
Answer:The examples illustrate the transition from
traditional API methods to rerunnable job resources. They
provide practical scenarios—like backing up chat rooms or
analyzing data—that showcase how abstractions are
implemented, highlighting the benefits of separation of
configuration and execution while depicting the API's
evolving design structure.

[Link]
Why is it important that execution resources are
immutable and not explicitly created by users?
Answer:Making execution resources immutable ensures that
they represent a consistent and unchangeable snapshot of a
job's output. This prevents accidental alterations that could
skew results and maintains data integrity. Furthermore,
having these resources created by internal processes
preserves the API's design logic and control.

[Link]
What lessons can we learn from the motivation behind
the use of rerunnable jobs?
Answer:The motivation underlines the need for maintaining
cleaner API interfaces that reduce complexity. By allowing
tasks to be defined once and executed multiple times,
rerunnable jobs encourage a more organized approach to
handling asynchronous operations and resource management
in APIs, making them easier to maintain and use.
Chapter 13 | 12 Singleton sub-resources| Q&A
[Link]
When should we consider using a singleton sub-resource
in API design?
Answer:Consider a singleton sub-resource when a
component of a resource is significantly large
compared to the resource itself, has different
security requirements, or is frequently changing.
For instance, in a ride-sharing API, the driver's
location data can change rapidly, warranting its
separation into a singleton sub-resource to optimize
data handling and security.

[Link]
What are the main benefits of implementing singleton
sub-resources?
Answer:The key benefits include improved separation of
concerns, reduced bandwidth usage since less data is
transmitted by default, and enhanced security by isolating
sensitive data that might have stricter access controls.
[Link]
How does the singleton sub-resource pattern affect API
interactions?
Answer:Interacting with a singleton sub-resource involves
using methods like GET and UPDATE similar to other
resources, but the creation of the sub-resource occurs
implicitly with the parent's existence. This means there's no
need to create the sub-resource explicitly, making it easier to
manage.

[Link]
What challenges may arise when transitioning from a
property to a singleton sub-resource?
Answer:One challenge is the loss of atomicity; updates to the
parent and sub-resource can't be guaranteed to occur
simultaneously. This separation means you might need to
handle updates in a way that's more complex than when all
data was housed in a single resource.

[Link]
Why might it be impractical to have multiple instances of
singleton sub-resources?
Answer:Having exactly one instance of a singleton
sub-resource helps maintain consistency and clarity in
resources. It prevents confusion over accessing or
manipulating multiple states of what should be a singular
representation of data, like a unique driver's location.

[Link]
What considerations should be made in determining the
size and complexity thresholds for splitting data into a
singleton sub-resource?
Answer:Consider the typical response times, the expected
frequency of data access vs. modification, and the average
size of data being handled. If a resource's sub-component is
expected to grow, or if it significantly impacts performance
by its size, it's time to consider creating a singleton
sub-resource.

[Link]
What are the implications of being able to reset a
singleton sub-resource in an API?
Answer:Resetting functionality allows developers to revert
the sub-resource to its default state, enhancing usability when
the parent resource is originally created. This feature can help
maintain the integrity of data and provide a clean slate
without necessitating complex initialization routines with
each update.

[Link]
How can separating sensitive data into singleton
sub-resources improve API security?
Answer:By isolating sensitive data like compensation
information from less sensitive employee metadata, access
controls can be stricter and more tailored. This approach
minimizes the risk of exposing sensitive data through broader
resource access routines.

[Link]
Why can't singleton sub-resources be children of other
singleton sub-resources?
Answer:This restriction ensures clear hierarchy and
management within API resource structures. If multiple
levels of singleton sub-resources could exist, it would create
unnecessary complexity and ambiguity, undermining the
benefits of having a clear, singular instance.

[Link]
In what scenario would deleting a parent resource also
necessitate deleting a singleton sub-resource?
Answer:When a parent resource is deleted, the necessary
cleanup of its dependent data follows, similar to database
cascading deletes. This ensures that original integrity is
maintained, and orphaned data doesn't persist unnecessarily,
saving resources and improving data management.
Chapter 14 | 13 Cross references| Q&A
[Link]
What is the main purpose of referencing resources in an
API?
Answer:The main purpose of referencing resources
in an API is to allow resources to point to one
another, facilitating relationships and enabling
interactions between different entities within the
system.

[Link]
Why is it important to have clear guidelines for
referencing resources?
Answer:Having clear guidelines for referencing resources is
crucial to prevent inconsistencies in how resources interact.
This clarity helps developers make informed choices about
possible actions, like what happens when a referenced
resource is deleted.

[Link]
What are the potential issues with referencing resources?
Answer:Referencing resources can lead to issues such as
dangling pointers if a resource is deleted but other resources
still reference it. This can create inconsistencies and
complicates data integrity.

[Link]
How can we ensure data integrity when referencing
resources?
Answer:To ensure data integrity when referencing resources,
guidelines should be established on what to do when a
referenced resource is deleted, such as preventing the
deletion of resources that are still being referenced.
[Link]
What is the difference between storing a reference and
storing a copy of resource data?
Answer:Storing a reference allows consumers to always
access the most current version of a resource, while storing a
copy keeps the data local but carries the risk of becoming
outdated.

[Link]
How should reference fields be named in an API?
Answer:Reference fields should typically be named using the
format 'XID', such as 'authorId', to convey the type and
purpose of the referenced resource clearly.

[Link]
What trade-offs exist between using references versus
storing copied resource data?
Answer:Using references requires multiple API calls to
retrieve associated data, which can increase complexity,
whereas storing copied data offers convenience but risks data
staleness and consistency issues.

[Link]
What is a dynamic resource type reference and when is it
necessary?
Answer:A dynamic resource type reference allows for
pointing to various types of resources where the type may
vary by context, necessary in situations like a change log
where different types of changes can occur.

[Link]
Why might an API consumer need to handle potentially
invalid references?
Answer:API consumers must be prepared for potentially
invalid references because when resources are deleted or
moved, references can become outdated, leading to errors if
not managed properly.

[Link]
What should API consumers expect regarding references
over time?
Answer:API consumers should expect that references may
become invalid, and they should implement checks to handle
instances where the resources they point to may no longer
exist.
Chapter 15 | 14 Association resources| Q&A
[Link]
What is the main motivation behind using association
resources in API design?
Answer:The motivation for using association
resources is to effectively manage many-to-many
relationships between resources while allowing for
the storage and management of additional metadata
about those relationships. This pattern enables
developers to explicitly address individual
relationships between resources, which is crucial for
accurately representing complex interactions, such
as the roles and timestamps associated with users
and groups.

[Link]
How should association resources be named when
designing an API?
Answer:When naming association resources, it is important
to choose a name that makes sense within the context of the
application. For example, in an API for a school, an
association resource might be named 'CourseEnrollment.'
The chosen name should reflect both resources being joined,
often leading to names like 'Membership' for users joining
groups. Clarity and context are key when identifying these
names.

[Link]
What standard methods should be implemented for an
association resource?
Answer:Each association resource should implement
standard methods including Create, Get, List, Update, and
Delete. These methods are essential for managing the
relationships effectively—Creating a membership, retrieving
details about it, listing associations, updating metadata, and
deleting associations when necessary.

[Link]
What uniqueness requirements are there for association
resources?
Answer:There is a strict uniqueness requirement for
association resources, which states that there should only be
one association resource that represents a specific pairing of
two resources. This ensures that a user cannot be a member
of a group more than once, thereby maintaining the integrity
of the relationships.

[Link]
Which strategies can be employed to handle referential
integrity in APIs?
Answer:Strategies for handling referential integrity can
include options like restricting the deletion of associated
resources, cascading deletes that remove associated
references, setting pointers to null when a resource is deleted,
or simply leaving references invalid. The choice depends on
the desired behavior of the API, balancing user experience
and system stability.

[Link]
What are the trade-offs of using association resources in
API design?
Answer:Using association resources allows for greater
flexibility and detailed relationships in an API but adds
complexity to the interface. This can lead to a steeper
learning curve for users who must navigate additional layers
of abstraction and multiple methods related to associations.
Moreover, it separates related pieces of information, which
might feel less intuitive.

[Link]
How can alias methods enhance the usability of an API?
Answer:Alias methods improve usability by providing
shortcuts for common queries related to associations, such as
retrieving all users in a group or all groups a user belongs to
without needing complicated filters. This makes the API
more intuitive and user-friendly, enabling quick access to
frequently needed information.

[Link]
What implications do read-only fields have in the context
of updating association resources?
Answer:Read-only fields in association resources indicate
that certain identifiers, such as user and group IDs, cannot be
changed during an update process. This ensures that the
association retains context and integrity, requiring users to
delete the old association if they want to create a new
relationship.

[Link]
Why is it crucial to maintain history in association
resources, and how can this be implemented in a chat
application?
Answer:Maintaining history in association resources is
crucial for tracking the dynamics of relationships over time,
especially in scenarios like chat applications where users can
join and leave rooms multiple times. To implement this, the
API could design the association resource to store
timestamps and roles for each entry, ensuring that duplicates
are avoided for users joining the same room.

[Link]
In which scenarios might you prefer to do nothing rather
than restrict deletion in an API?
Answer:Choosing to do nothing when deleting associated
resources can be appropriate in situations where legacy data
needs to be preserved for audit purposes. This approach
allows the system to continue functioning even with
'dangling' references, leaving resolution of such references to
be handled later by the API consumer.
Chapter 16 | 15 Add and remove custom methods|
Q&A
[Link]
What are the key motivations behind using custom add
and remove methods for managing many-to-many
relationships in APIs?
Answer:The key motivations are to simplify the API
design by avoiding the complexity of an explicit
association resource; manage relationships without
needing to track metadata; and create a more
intuitive interface for the consumer by using
straightforward add and remove methods for
linking two resources together.

[Link]
What limitations should developers be aware of when
utilizing custom methods to manage relationships?
Answer:Developers should be aware that using this pattern
restricts the ability to store relationship metadata, such as
timestamps or roles within the association, and requires
choosing one resource as the managing one, leading to a
nonreciprocal association.

[Link]
How can custom methods enhance the intuitiveness of an
API? Can you provide an example?
Answer:Custom methods enhance intuitiveness by providing
clear, action-oriented commands like 'add' and 'remove',
which are straightforward for API consumers to understand.
For instance, using '[Link](userId)' to add a user to a
group is more intuitive than managing an entire association
resource.

[Link]
In what scenarios would using add and remove methods
be more appropriate than traditional association
resources?
Answer:Using add and remove methods is more appropriate
in scenarios where the application does not require complex
metadata about relationships, such as a simple user and group
membership system where tracking join dates or roles is
unnecessary.

[Link]
What should an API return if an attempt is made to add a
user that is already in the group?
Answer:An API should return a '409 Conflict' response,
indicating that the attempted action is invalid due to the
resource already existing in the target collection.

[Link]
How do you determine which resource should be the
managing resource in a many-to-many relationship?
Answer:Determining the managing resource often depends
on the context of the relationship; for example, in a user and
group case, if users are frequently added to different groups
by administrators, groups might be the managing resource,
while the reverse could be true in a user-driven model where
users manage their own memberships.

[Link]
Can you clarify the importance of error responses in the
context of add/remove methods?
Answer:Error responses are critical because they provide
feedback on the operation's result, ensuring consumers can
understand whether their request was successful or if the
desired state was already achieved. This reinforces the
simplicity of achieving the necessary relationships without
excessive control flow.

[Link]
What is the difference between listing associations using
standard methods versus using custom methods?
Answer:Listing associations using standard methods involves
fetching a list of resources directly, typically through a
defined endpoint like 'GET /groups/1/users', while custom
methods would allow querying specific subcollections based
on the context of the managing resource, like
'ListGroupUsers'.

[Link]
Explain the trade-off between simplicity and functionality
when using custom methods for associations.
Answer:The trade-off lies in the balance between having a
clean, simpler API interface and the potential loss of
functionality such as the ability to store detailed metadata
about relationships or having to make a potentially arbitrary
decision about which resource manages another.

[Link]
What are some exercises developers can engage in to
better understand this API design pattern?
Answer:Developers can explore how to decide on managing
versus associated resources in different contexts, determine
method naming conventions for listing associated resources,
and case-study the implications of trying to add duplicates or
manage nonexistent relationships.
Chapter 17 | 16 Polymorphism| Q&A
[Link]
What is polymorphism in the context of APIs, and why is
it important?
Answer:Polymorphism allows resources in an API
to take on various forms, typically using a common
interface for different implementations. This helps
in minimizing code duplication and makes the API
cleaner and more modular. It is important because it
enables developers to write generic code that can
handle multiple resource types while abstracting
away the specific details of each type.

[Link]
When should polymorphic resources be used in API
design?
Answer:Polymorphic resources are best used when there is a
commonalities among different resource types, such as
listing all messages in a chat room irrespective of their
format (text, audio, or video). If users expect to operate on
multiple resource types together, polymorphism simplifies
the interface and enhances usability.

[Link]
What are the risks of using polymorphic methods instead
of polymorphic resources in APIs?
Answer:Polymorphic methods can lead to confusion and
inconsistency because they attempt to handle different
resource types under a single method. This can create
maintenance challenges and could limit the future flexibility
of the API. Each resource may have specific behaviors and
requirements that need to be addressed individually.

[Link]
What kind of field should be used to represent the type in
polymorphic resources, and why?
Answer:A simple string field is recommended for
representing the type in polymorphic resources instead of an
enumeration. This allows for more flexibility in managing
the types and avoids the shortcomings of enumerations,
which can complicate API versioning and maintenance.

[Link]
How should an API handle additional data that isn’t
relevant to the resource type being created or updated?
Answer:Instead of rejecting the request with an error for
irrelevant data, the API should validate the required fields
and ignore any extraneous data. This approach maintains user
experience while preventing unnecessary errors.

[Link]
Why is it discouraged to change the type of a
polymorphic resource once it has been created?
Answer:Changing the type of a polymorphic resource can
break assumptions made by other resources that reference it,
leading to potential bugs and user confusion. It’s better to
avoid changing types to maintain the integrity of the API.

[Link]
What is a critical consideration when designing a
polymorphic resource?
Answer:A key consideration is ensuring that the resource
structure aligns with the behaviors expected from each
subtype. The resource must be designed in a way that
maintains practicality while accommodating the specific
requirements of its subtypes.

[Link]
Can you provide an example illustrating the concept of
polymorphism in an API?
Answer:In a polymorphic API for messages, you might have
a generic 'Message' resource with a 'type' field indicating
whether it is a 'text', 'photo', or 'video'. For each type, the API
can respond differently to the same method, like
'getContent()', depending on its specific type.
Chapter 18 | 17 Copy and move| Q&A
[Link]
What are the main challenges associated with moving or
copying resources in an API?
Answer:The main challenges include ensuring
atomicity of operations, maintaining referential
integrity (updating references that point to moved or
copied resources), handling child resources that
must also be moved or copied, dealing with external
references, establishing unique identifiers for newly
created resources, and managing inherited metadata
from parent resources. Each of these challenges can
lead to data corruption or unexpected behavior if
not handled carefully.

[Link]
How should APIs handle the scenario of a user wanting to
rename a resource?
Answer:APIs should provide a custom method for renaming
resources as standard update methods are not sufficient.
When renaming, the API must ensure that the new identifier
is unique and adheres to any user-specified identifier
policies. Additionally, the API should handle any related or
affected resources to ensure consistency and referential
integrity.

[Link]
What is the importance of atomicity in copy and move
operations?
Answer:Atomicity is crucial for ensuring that operations
either complete successfully or have no effect at all. This
prevents partial updates that could lead to data
inconsistencies. APIs should aim to execute copy and move
operations within a transactional context to maintain data
integrity.

[Link]
How does moving a resource from one parent to another
affect its child resources in an API?
Answer:When moving a resource, all its child resources must
also be updated to reflect the new parent. This involves
updating the identifiers of the child resources to fit into the
new hierarchy while ensuring that all related references and
metadata are also adjusted to maintain consistency.

[Link]
What are the best practices for maintaining referential
integrity when copying resources?
Answer:Best practices include ensuring that all related
resources are also copied along with the target resource,
updating any references that point to the original resource,
and handling user expectations by clarifying what happens to
related resources. For related but non-child resources, it may
be best not to duplicate them unless necessary.

[Link]
In what circumstances should a resource and its
associated data be copied by reference versus copied by
value?
Answer:Resources that involve large amounts of data, such
as files, should often be copied by reference to save on
storage and processing resources until a change is made,
triggering a full copy. In contrast, for smaller or more
constrained resources, a copy by value might be more
appropriate to maintain data integrity.

[Link]
How can APIs ensure that they do not break external
references when moving resources?
Answer:APIs should acknowledge that maintaining external
reference integrity is often not feasible and thus should
communicate this limitation clearly. Whenever a resource is
moved, it's vital to use best-effort principles for these
references, understanding that they might lead to broken
links without a guarantee of future access.

[Link]
What considerations should be taken into account when
implementing copy and move operations in an API
design?
Answer:Considerations include discernment between
copying and moving, the implications of user-specified
identifiers, the performance implications on system
resources, and potential impacts on user experience if
operations fail or result in inconsistent states. It's also
essential to understand the broader consequences on data
integrity and API usability.

[Link]
Why might copying resources be more desirable than
moving them in an API?
Answer:Copying resources allows users to maintain the
original while creating a new version, which can lead to safer
data operations. Moving often results from poor design or
user errors, thus copying can serve as a more reliable and
user-friendly method.
Chapter 19 | 18 Batch operations| Q&A
[Link]
Why should batch operations be atomic?
Answer:Batch operations must be atomic to ensure
that either all operations succeed or none do. This is
essential to maintain data integrity; for example,
when updating multiple resources, if one fails while
others succeed, the state of the system could become
inconsistent. Ensuring atomicity simplifies error
handling since the API client does not need to deal
with partial updates.

[Link]
What are the common methods in batch operations?
Answer:Common methods in batch operations include
BatchGet, BatchCreate, BatchUpdate, and BatchDelete. Each
of these methods allows the client to perform actions on
multiple resources in a single request instead of making
individual requests for each resource.

[Link]
How can common fields be handled in batch requests?
Answer:Common fields in batch requests can be hoisted up
to avoid repetition, meaning instead of repeating the same
data (like the parent field), it can be defined once for the
entire batch request. This reduces redundancy and simplifies
the structure of requests.

[Link]
What is the significance of ordering results in batch
methods?
Answer:Ordering is crucial in batch methods because the
client often relies on the order in which resources are
provided to match them with the responses. If results come
back out of order, it complicates processing on the client side
and could lead to errors or confusion.

[Link]
What happens if a hoisted field conflicts with an
individual request in a batch operation?
Answer:If a hoisted field conflicts with an individual request,
the API should reject the batch request as invalid. This
approach prevents misunderstanding of user intentions and
maintains the clarity of the request structure.

[Link]
Why is using a wildcard for multiple parents beneficial in
batch requests?
Answer:Using a wildcard allows clients to specify that the
batch request can involve resources from multiple parents
without tightly coupling the request to specific identifiers
ahead of time. This flexibility makes it easier to handle group
operations that span different types or categories of
resources.

[Link]
What is the trade-off of emphasizing atomicity in batch
methods?
Answer:The trade-off of emphasizing atomicity is that it may
lead to more failures if even one operation in the batch
encounters an error. This can be seen as inconvenient in
scenarios where a client might prefer partial success, but it
simplifies the API function and maintains a predictable
behavior similar to transactions.
[Link]
How should the API respond if the parent field specified
in a batch update request does not match any of the
resources being updated?
Answer:The API should return an error indicating an invalid
request when there's a mismatch between the parent field of
the request and any of the resources being processed. This
prevents unexpected behavior and enforces clarity in the
operation.
Chapter 20 | 19 Criteria-based deletion| Q&A
[Link]
What are the primary concerns regarding the custom
purge method in API design?
Answer:The primary concerns include the risk of
accidentally deleting important data due to user
errors, as the method can delete all resources
matching a filter without the user fully
understanding the implications. Additionally, the
method operates in a way that can lead to
non-atomic results, meaning by the time resources
are deleted, the context around them (like their
archived status) may have changed.

[Link]
How can the purge method be safe despite its inherent
risks?
Answer:The purge method incorporates guardrails such as
requiring an explicit Boolean flag ('force') to be set for
deletion requests, ensuring that no resources are deleted
unless this flag is explicitly included. Additionally, the
method provides a preview feature that shows how many
resources would be deleted and a sample of those resources
before any deletion occurs.

[Link]
Why should the purge method only be implemented when
absolutely necessary?
Answer:The purge method can pose significant risks of data
loss. It should only be used when there is a clear necessity
because it gives users a powerful tool that could
inadvertently lead them to delete vast amounts of data
quickly and with little oversight.

[Link]
What is the significance of the purgeCount and
purgeSample responses in the purge method?
Answer:The purgeCount provides the user with a count of
how many resources would be affected by the purge request,
offering insight into the potential impact of the action. The
purgeSample provides a subset of resources that match the
filter, allowing users to verify which resources are targeted
for deletion, thus mitigating the risk of accidental data loss.

[Link]
How does the design of the purge method address
concerns about data consistency between validation and
deletion?
Answer:While the purge method cannot guarantee data
consistency due to the possibility of concurrent changes in
the dataset, it allows users to validate results initially and
execute the deletion later. However, there is still a
recognition that the data may have changed during this
process, potentially leading to unexpected outcomes.
[Link]
What should developers consider when defining filters for
the purge method?
Answer:Developers must ensure that filters are designed
carefully to avoid unintended matches. An empty or invalid
filter could lead to the deletion of all items in a data set,
emphasizing the need for stringent validation and error
handling when constructing filter criteria.

[Link]
Why is it essential for the purge method to have a default
behavior of validation-only?
Answer:Making the purge method default to validation-only
helps prevent unintentional data losses. If the user forgets to
set the force flag, the method will not delete any data but will
instead provide insights into what would be purged, enabling
the user to make informed decisions.

[Link]
What are the potential issues caused by underestimating
the number of resources that will be purged?
Answer:Underestimating the number of resources can lead to
a false sense of security, causing users to proceed with a
deletion operation thinking less data will be lost than actually
will. If actual numbers are significantly higher than the
estimate, users may be unprepared for the consequences of
their actions.

[Link]
How does the design of the purge method strive for
consistency with the standard list methods?
Answer:The design aims to ensure that filters behave the
same way across both the purge and list requests,
maintaining user expectations when working with API calls.
This consistency is crucial for users to understand and trust
the behavior of the API without needing to adjust their
mental models.

[Link]
Why is it critical to provide a sample set of resources that
matched the filter in the purge method?
Answer:Providing a sample set allows users to verify that
their filter criteria are correct before proceeding with
deletion. This step is essential to catch potential mistakes in
the filter setup and to give users assurance that they will not
accidentally delete unintended data.
Chapter 21 | 20 Anonymous writes| Q&A
[Link]
What is the significance of using anonymous data in API
design?
Answer:Using anonymous data allows APIs to
handle scenarios where data needs to be ingested
without creating uniquely identifiable resources.
This approach is particularly useful in cases such as
logging or time series data where aggregates are
more important than individual data points. It
streamlines the design and implementation of APIs
for analytical purposes, promoting efficiency and
reducing overhead.

[Link]
How does the custom 'write' method differ from standard
resource creation methods?
Answer:The 'write' method differs as it does not create
identifiable resources that can be retrieved or updated later.
Instead, it simply ingests data as anonymous entries, focusing
on aggregate statistics rather than individual records. This
method helps address challenges faced in analytical systems
where users are typically more interested in trends and
summaries than detailed data points.

[Link]
Why is it important for the write method to return no
response body, and what should it return instead?
Answer:The write method should return no response body
because there's no identifiable resource to return after the
data is ingested. Instead, it should provide a straightforward
status code (like HTTP 202 Accepted) to confirm that the
data was received for processing. This approach aligns with
the goal of maintaining an efficient and consistent API for
handling large-scale analytics.

[Link]
In what circumstances should a write method
communicate that data was received but not yet
processed?
Answer:A write method should communicate data receipt
without immediate processing using an HTTP 202 Accepted
status code. This informs users that their data is in the
ingestion pipeline but may take time before it is visible or
aggregated. It’s crucial for transparency, especially in
systems reliant on eventual consistency.

[Link]
What strategies can be implemented to prevent duplicate
data ingestion via the write method?
Answer:To prevent duplicate data ingestion, APIs can utilize
request deduplication patterns that involve providing unique
identifiers for requests or verifying incoming data against
existing stored aggregates. Implementing proper checks and
validations at the API level ensures data integrity and
consistency in the analytics process.

[Link]
What is the broader context for the necessity of a custom
write method in API design?
Answer:The necessity for a custom write method arises from
the unique nature of analytical data, which diverges from
traditional transactional data management. Standard methods
are ill-equipped to handle the rapid ingestion and processing
requirements of analytical workloads, prompting the need for
a design that emphasizes streamlined data handling,
efficiency, and aggregate-focused interactions.
Chapter 22 | 21 Pagination| Q&A
[Link]
Why is pagination important in API design?
Answer:Pagination allows the delivery of large
datasets in manageable chunks, enhancing user
experience and system performance. It prevents
overwhelming consumers with excessive data and
enables them to retrieve specific subsets of
information efficiently.

[Link]
How does pagination improve API performance?
Answer:By splitting data into smaller pages, pagination
minimizes the amount of data each request processes at one
time, reducing server load and response time. This efficiency
is crucial when dealing with vast amounts of data, like a
billion entries.

[Link]
What questions arise when implementing pagination in
an API?
Answer:Key questions include how to determine chunk sizes,
how to indicate the end of data, and how to represent the
page tokens used for navigating between data chunks.

[Link]
What is the difference between maxPageSize and exact
page size in pagination?
Answer:Using maxPageSize allows flexibility since servers
can return fewer results based on system constraints, while
supplying an exact page size may require processing more
data than is viable given performance limitations.

[Link]
What are the possible consequences of not having a total
count in API responses?
Answer:Without a total count, users might struggle to
navigate or understand the scope of their results, particularly
in user interfaces where knowing the total entries helps in
displaying pagination controls effectively.

[Link]
How can API servers indicate that pagination is
complete?
Answer:API servers signal the end of pagination by returning
an empty nextPageToken, rather than relying on the results
array being empty, as this provides clearer communication
about available data.

[Link]
Why is it important to keep page tokens opaque to users?
Answer:Keeping page tokens opaque prevents users from
manipulating implementation details that could lead to errors
or changes in behavior. It allows the API to evolve without
breaking existing client integrations.

[Link]
What approach should be used when page tokens might
expire?
Answer:API documentation should clarify the expected
lifetime of page tokens to manage consumer expectations
around attempting to retrieve pages after a prolonged delay.

[Link]
What types of scenarios might require paging within a
single resource?
Answer:Paging within a single resource may be necessary
when the resource itself is large, such as files or databases,
allowing users to build their understanding of the resource
incrementally.

[Link]
What issues can arise from using offsets in pagination?
Answer:Using offsets can lead to inconsistent results if new
data is added or removed between requests, causing users to
see duplicate or missing records when navigating through
pages.

[Link]
What is the recommended default value for maxPageSize
and why?
Answer:The recommended default is usually around 10
results per page, as this balances server performance with
user experience, ensuring that consumers receive data in
manageable quantities.

[Link]
How can pagination support both scalability and
usability?
Answer:By implementing thoughtful pagination practices,
APIs can efficiently manage large volumes of data while still
providing a user-friendly interface for navigating and
consuming that data.

[Link]
Why should consumers have control over pagination
parameters like maxPageSize?
Answer:Allowing consumers to specify maxPageSize gives
them flexibility in managing their data consumption based on
their needs, ultimately improving their overall experience
with the API.

[Link]
What trade-offs exist with bi-directional paging?
Answer:While bi-directional paging can enhance user
experience for applications needing to browse data
backwards, it may not be essential for programmatic
interactions, leading to potential design complexity.

[Link]
What is a significant anti-pattern to avoid in pagination,
and why?
Answer:Avoid using simple OFFSET and LIMIT parameters
directly in APIs, as they expose implementation details, can
lead to performance issues, and compromise the integrity of
results due to data changes.
Chapter 23 | 22 Filtering| Q&A
[Link]
What is the main motivation for incorporating filtering in
the standard list methods of an API?
Answer:The primary motivation is to allow users to
retrieve a specific subset of resources that match
certain criteria, rather than forcing them to fetch all
resources and then filter them on the client side.
This enhances efficiency and reduces unnecessary
data transmission.

[Link]
How should filtering criteria be communicated to the API
server?
Answer:Filtering criteria should be communicated as a
special 'filter' field in the standard list method request. This
can be expressed as a string value, resembling SQL query
syntax, allowing flexibility and ease of use for clients
familiar with such formats.

[Link]
What are the pros and cons of unstructured versus
structured filtering methods?
Answer:Unstructured filtering, like string queries, offers
greater flexibility and is generally easier for clients to use
because it often resembles familiar SQL syntax. However,
structured filtering can provide clearer schemas but may
complicate API evolution and usability. The choice depends
on the context and anticipated API changes.

[Link]
Why is it important to limit the context of filtering
evaluations to a single resource?
Answer:Limiting filtering evaluations to a single resource
prevents computationally expensive operations that could
arise from needing additional resources for comparisons.
This ensures that the evaluation remains efficient and
manageable.

[Link]
In filtering criteria, why should array fields be treated as
unordered?
Answer:Arrays should be treated as unordered because
requiring specific positions for values in arrays can lead to
inconsistencies and complexity. Users typically want to
know if a certain value exists within the array, irrespective of
its position.

[Link]
What should be done when a filtering expression contains
invalid field names?
Answer:The API should respond with an error message that
clearly indicates the issue, rather than silently ignoring the
mistake. This enhances user experience by helping them
quickly identify and correct their errors.

[Link]
What is a fundamental limitation regarding the
complexity of operations allowed in filter expressions?
Answer:Filters should not allow complex operations that
require external communication or state information beyond
what is provided in the resource being evaluated. This
isolation helps prevent performance issues due to external
dependencies.

[Link]
How can APIs allow for advanced filtering without
complicating the fundamental syntax?
Answer:APIs can support advanced filtering by providing
special functions within the filter expressions, allowing users
to perform more complex queries without altering the basic
syntax rules or overwhelming users with complexity.

[Link]
What is one significant trade-off when implementing
resource filtering in an API?
Answer:One significant trade-off is between the
computational cost of implementing filtering and the user
benefit of avoiding unnecessary data retrieval. The
advantages of providing efficient, relevant results typically
outweigh the costs associated with implementation.

[Link]
What should the API designer prioritize when creating a
filtering system?
Answer:API designers should prioritize usability and
flexibility, ensuring that the filtering system can adapt to
changing requirements while remaining intuitive for users.
Chapter 24 | 23 Importing and exporting| Q&A
[Link]
What is the primary motivation for directly importing
and exporting data between an API and an external
storage system?
Answer:The primary motivation is to improve
efficiency by minimizing the unnecessary data
transfer to an intermediary application server. By
allowing the API to communicate directly with the
storage system, it reduces wasted bandwidth and
compute resources, leading to faster and more
efficient data operations.

[Link]
Why is it important to have separate interfaces for
configuring import and export methods?
Answer:Separate interfaces for import and export methods
help in clearly defining the responsibilities of each
configuration type, reducing confusion and allowing for
necessary options specific to either input or output without
overwhelming a single combined interface.

[Link]
What challenges arise when exporting data that may
change during the export operation?
Answer:The main challenge is ensuring data consistency. If
data is modified concurrently while being exported, it can
lead to a 'smear' of exported data that does not accurately
represent the state of the data at a specific point in time.
Solutions may include relying on the underlying storage
system's snapshot capabilities or acknowledging that
exporting a smear might be the only viable option.

[Link]
How should overlapping identifiers be handled during the
import of resources?
Answer:When importing resources, if an identifier already
exists in the API, it is best practice to ignore the existing
identifier and assign a new one to avoid duplicate entries.
This approach is aligned with the focus of import and export
methods being about data movement rather than strict
identifier preservation.

[Link]
What are the key differences between exporting data and
backing up data?
Answer:Exporting data is about retrieving resources and
moving them directly to an external location without
ensuring consistency, while backing up data implies creating
a specific snapshot of the data with guarantees that the stored
data can be restored completely and accurately. Exporting
operates under the assumption that the data may not represent
a single point in time.

[Link]
What kind of failures might occur during import and
export operations, and how should they be dealt with?
Answer:Import failures can arise from validation errors or
transient issues, and each case may necessitate a different
response—while export failures can generally be retried
safely as they do not affect the source data. Import operations
must ensure to track created entries to prevent duplication
upon retries.

[Link]
What role does filtering play in the import and export
process of API resources?
Answer:In the export process, filtering is crucial as it allows
specific resources to be selected for export before any
serialization occurs. However, for imports, filtering can be
challenging and generally should be avoided, as the API
should not have to apply filtering logic during the data
loading stage.

[Link]
How do unique identifiers affect the import/export
process of resources in APIs?
Answer:Unique identifiers are complex during imports and
should typically be ignored if they conflict with existing ones
to prevent duplication. During exports, however, maintaining
identifiers is essential for referencing the resources reliably
during future operations, despite the trade-off of possible
collisions when re-importing those resources.

[Link]
Why is it essential to understand the distinction between
import/export operations and traditional backup/restore
mechanisms?
Answer:Understanding this distinction is crucial because
import/export operations are about data movement without
consistency guarantees, while backup/restore operations
require strict adherence to preserving the state of the data at a
point in time, which is vital for recovery processes.

[Link]
How should related resources be handled in API
import/export methods?
Answer:Import/export methods are designed to move
self-contained data between an API and an external system.
Generally, they should focus on individual resource types
rather than attempting to address related resource hierarchies,
as the complexity could blur the line between simple data
moving and more intricate backup and restore functionalities.
Chapter 25 | 24 Versioning and compatibility| Q&A
[Link]
What is the main challenge addressed in this chapter
regarding the evolution of web APIs?
Answer:The chapter dives into how to evolve web
APIs without causing inconvenience to existing users
who rely on them, highlighting the need for a robust
versioning strategy to manage changes while
maintaining backward compatibility.

[Link]
How does versioning in APIs help in minimizing user
inconvenience?
Answer:Versioning allows an API to introduce new features
or changes while keeping the older versions available,
ensuring that existing users can continue using the API
without disruption.

[Link]
What does backward compatibility mean in the context of
API design?
Answer:Backward compatibility refers to the ability of a new
version of an API to work with existing client-side code,
meaning that if a user upgrades to a newer version, their
previous functionality should not break.

[Link]
Why is the question of how to determine backward
compatibility considered complicated?
Answer:Determining backward compatibility is complicated
because it often depends on the specific user expectations
and how changes might interact with different combinations
of clients and servers, making it subjective.

[Link]
What are the trade-offs to consider when choosing a
versioning strategy for APIs?
Answer:When choosing a versioning strategy, one must
weigh the granularity and simplicity of versions, stability
versus new functionality, and the satisfaction of different
user groups against the accessibility of the API.

[Link]
How does agile instability as a versioning strategy
operate?
Answer:The 'agile instability' strategy focuses on
maintaining a limited number of active API versions,
promoting continuous improvement while requiring users to
adapt to periodic deprecations.

[Link]
Why is semantic versioning favored in API design?
Answer:Semantic versioning is favored because it provides
meaningful version numbers (major, minor, patch) that
communicate the nature of changes made, allowing users to
easily understand the implications of version upgrades.

[Link]
What should API designers consider when handling
mandatory changes, such as legal requirements?
Answer:Designers should evaluate whether to inject such
changes into existing versions or create new versions,
focusing on minimizing user stress and providing adequate
notice before implementing changes.

[Link]
What is the goal when balancing user happiness and API
usability?
Answer:The goal is to find a middle ground where maximum
usability is achieved without alienating users, ensuring that a
diverse user base can effectively use the API while also
catering to their varying expectations.

[Link]
In the context of fixing bugs, when should changes be
implemented as a new version?
Answer:Changes that result in different behavior than what
users expect, such as altering successful outcomes to errors,
should typically be treated as requiring a new version to
avoid breaking existing user code.
Chapter 26 | 25 Soft deletion| Q&A
[Link]
What is the main purpose of soft deletion in APIs?
Answer:Soft deletion allows resources to be marked
as deleted without permanently removing them from
the database. This provides a safety net for
accidental deletions, enabling users to recover
resources if needed.
[Link]
How does soft deletion prevent accidental data loss?
Answer:By marking resources as deleted instead of
permanently removing them, soft deletion provides an
opportunity to recover data that may have been deleted
mistakenly, similar to a recycle bin in operating systems.

[Link]
What modifications are required for standard methods
when implementing soft deletion?
Answer:Standard methods need to be altered to mark
resources as deleted and include new custom methods for
undeleting and expunging resources. For example, the
standard delete method should modify the deleted status
rather than removing the resource.

[Link]
Why might a Boolean flag be preferable to a state field
for indicating soft deletion?
Answer:A Boolean flag is simpler to implement and fits
naturally with the concept of soft deletion, indicating only
whether a resource is deleted or not. A state field complicates
the model as it introduces multiple potential states.

[Link]
What potential issues arise when undeleting a resource
that is not currently soft deleted?
Answer:Attempting to undelete a resource that is not soft
deleted should return an error indicating that the operation
cannot be performed since the resource is already in an active
state.

[Link]
How do expiration policies fit into the soft deletion
model?
Answer:Expiration policies can be implemented to
automatically permanently delete resources after a certain
period, combining soft deletion with time-based data
lifecycle management.

[Link]
What considerations should be taken into account for
referential integrity when implementing soft deletion?
Answer:The existing referential integrity rules should remain
applicable during soft deletion. If a resource is referenced by
others, soft deletion should not break these references
without careful consideration.

[Link]
What does the custom expunge method do in the context
of soft deletion?
Answer:The custom expunge method permanently removes a
resource from the API, overriding the soft deletion status and
ensuring complete removal from the storage system.

[Link]
How can users request to see soft-deleted resources in a
list?
Answer:Users can indicate their desire to view soft-deleted
resources by including a specific parameter in their request,
such as includeDeleted set to true.

[Link]
What is the trade-off of implementing soft deletion in
APIs?
Answer:The trade-off involves balancing between the
necessity of permanent removal of certain data as required by
regulations and the flexibility of allowing recoverable
deletions to prevent accidental loss.
Chapter 27 | 26 Request deduplication| Q&A
[Link]
Why do we need request identifiers in API design?
Answer:Request identifiers help to prevent duplicate
requests in an API, especially for non-idempotent
methods. They ensure that the API can distinguish
between a unique request and a retried one, allowing
the service to respond correctly without performing
the same operation multiple times. This is crucial in
a world where requests might fail or where network
unreliability can lead to packets being lost.

[Link]
What are the two scenarios when a client does not receive
a response to a request?
Answer:The two scenarios are: 1) The request was never
received by the API server, which can be resolved by simply
retrying the request, as it’s as if it never happened; 2) The
request was received and processed by the server, but the
response was not received by the client. In this case, it’s
unclear whether the operation was successful or not,
necessitating a mechanism to safely retry without duplicating
work.

[Link]
How can we handle duplicate requests efficiently?
Answer:By using a unique identifier for each request, we can
track whether a request has already been processed. When a
duplicate request is detected, instead of executing it again,
the API can return the cached response associated with the
original request ID. This ensures that clients get the expected
response without unnecessary repeated processing.

[Link]
What are the implications of request ID collisions?
Answer:Request ID collisions can result in confusing
outcomes where a response meant for one client gets
mistakenly returned to another client because they chose the
same request ID. To mitigate this, APIs should check not
only the request ID but also ensure the request body matches
the cached entry to confirm that it is truly a duplicate request
and not a different one using the same ID.

[Link]
Why is it not advisable to derive request identifiers from
the request content itself?
Answer:Deriving request identifiers from the request content
does not accurately capture the client's intent. It could lead to
erroneous behavior where a request is incorrectly assumed to
be a duplicate of a different request due to minor variations
in content. It's better to allow clients to specify unique
identifiers explicitly for clarity and control.

[Link]
How should caching work in the context of request
deduplication?
Answer:Caching should store the responses associated with
request IDs. When a request with a given ID is received, the
API first checks the cache to see if a result is already
available. If found, it returns the cached value, thus improved
performance and reducing redundant processing. The cache
expiration needs to be managed carefully - a reasonable
default is to retain cached entries for around five minutes,
refreshing this timer on each access to account for requests
that may be retried.

[Link]
Why is it critical to maintain consistency in responses
even with caching?
Answer:It’s vital to maintain the expected response from the
client’s perspective even if underlying data changes, to
prevent confusion. If clients retry requests due to lost
responses, they should receive the same outcome they would
have initially, even if that result reflects stale data. This
ensures predictability in behavior while adhering to the
deduplication goals.

[Link]
What are the recommended practices for expired cache
management in API requests?
Answer:Caches for request responses should expire after a
set duration, such as five minutes, to balance memory usage
and response speed. The expiration timer should reset each
time a cached value is accessed, acknowledging that repeated
retries tend to happen relatively soon following a failure.
This approach is easy to adjust based on system performance
and capacity needs.

[Link]
What is a good strategy for implementing request
identifiers in an API?
Answer:Implementing request identifiers involves defining a
request identifier field in the API request structure that
clients must populate when making requests meant to be
deduplicated. The API should explicitly check for uniqueness
upon receipt and validate that duplicated identifiers correlate
with matching request bodies to avoid unintended side
effects from collisions.

[Link]
What trade-offs must be considered when introducing
request deduplication in an API?
Answer:The trade-offs include increased complexity in API
method implementations and potentially higher memory
requirements due to caching needs. While some APIs may
not require strict deduplication, others, particularly those
dealing with sensitive operations, might need to employ
request identifiers to prevent issues resulting from duplicate
transactions.
Chapter 28 | 27 Request validation| Q&A
[Link]
Why is it important to support validation requests in
APIs?
Answer:Supporting validation requests is crucial
because APIs can be complex, and users often make
mistakes when executing them. By allowing users to
test API calls without making changes, we can
prevent unintended consequences, especially in cases
of dangerous commands that could affect
production systems.

[Link]
What does the validateOnly flag achieve in API requests?
Answer:The validateOnly flag allows users to request a
preview of the response without executing the action. This
means that users can receive validation feedback on their
requests, discover potential errors, and ensure that everything
is correct before making any permanent changes.

[Link]
How does human error factor into API usage and
validation?
Answer:Human error is a significant concern in API usage.
When verifying permissions or checking request validity, it's
easy to overlook a crucial detail. Validation requests help
mitigate this by providing a way to test requests without the
risk associated with executing them.

[Link]
Why should some API methods support validation
requests while others do not?
Answer:Not all API methods lend themselves to validation
requests due to their functionalities and potential side effects.
For instance, methods that inherently involve risky
operations may not benefit from validation; instead,
providing validation requests should focus on those methods
where users need confirmation without execution.

[Link]
What challenges arise from external dependencies when
validating requests?
Answer:External services or libraries can complicate
validation since they may not recognize validation requests
as non-executing operations. In these cases, the best practice
is to stick to the rules of safety and idempotence, validating
only those aspects that do not invoke external changes.

[Link]
How should an API respond to validation requests?
Answer:An API should return plausible results that reflect
what would happen if the request were executed, without
actually causing any changes. For successful validation, it
should indicate all potential errors clearly and represent an
estimated normal response.

[Link]
What trade-offs exist when implementing validation in
APIs?
Answer:While validation requests can streamline user
experience and reduce errors, they introduce complexity to
the API design. Not every method may require validation,
and their utility often depends on the users' interactions to
identify common mistakes before executing potentially
harmful actions.

[Link]
How can keeping responses realistic, even for validation
requests, be achieved?
Answer:Responses should aim to match expected outcomes
as closely as possible, providing accurate feedback regarding
success or failure, mimicking real execution where feasible.
This helps users understand the implication of their requests
without the risk of performing the action.

[Link]
In what scenarios is it acceptable to send validation
requests to external services?
Answer:It is only acceptable if the external service supports
the concept of validation without executing actions. If
validation requests would trigger side effects, those
interactions should be avoided to maintain the integrity and
safety of the validation process.
Chapter 29 | 28 Resource revisions| Q&A
[Link]
What are the primary motivations for implementing
resource revisions in an API?
Answer:The primary motivations for implementing
resource revisions in an API include preserving the
history of changes made to a resource, allowing for
the retrieval of past states of a resource, enabling
functionalities like rolling back to previous
revisions, and enhancing the ability to diagnose and
resolve issues by understanding how and when
changes occurred. This historical tracking is
especially beneficial for resources that represent
important documents, contracts, or other critical
data that may need to be reviewed or reinstated.

[Link]
How do we distinguish between implicit and explicit
revision creation in an API?
Answer:Implicit revision creation occurs automatically
whenever a modification is made to a resource, meaning
users do not need to take any extra action to create a revision;
every change results in a new historical record being saved.
Explicit revision creation, on the other hand, requires users to
actively request a new revision, often through a specific API
call that instructs the system to take a snapshot of the current
state of the resource at that moment.

[Link]
Why is it beneficial to use random identifiers for revisions
instead of incrementing numbers or timestamps?
Answer:Using random identifiers for revisions avoids
confusion and maintains the integrity of revision history,
especially when revisions are deleted. Incrementing numbers
can leave gaps that indicate deletions, while timestamps may
face collisions during high-concurrency situations. Random
identifiers provide a unique, opaque representation that
ensures no visible gaps in the revision history, presenting a
clean and consistent interface for users.

[Link]
What should happen when attempting to restore a
resource to a previous revision that is already the current
state?
Answer:If a user attempts to restore a resource to a previous
revision that matches its current state, the operation should
ideally be blocked with a 'no change' response. This prevents
unnecessary revisions from being created and avoids
confusion over the state of the resource.

[Link]
How does the API handle the restoration of previous
revisions while maintaining a clear history?
Answer:Restoration of previous revisions is handled by
creating a new revision that copies the state of the resource
from the older revision, rather than modifying the existing
revision. This ensures the historical record is preserved,
allowing users to see the resource's evolution over time while
concurrently marking the new revision as the active state.

[Link]
What trade-offs should API designers consider when
implementing resource revisions?
Answer:API designers should consider the increased
complexity in both the design and usage of the API, as well
as potential storage space requirements due to retaining
historical data. While resource revisions are fundamental for
certain use cases, they can complicate interactions and
necessitate careful design to prevent confusion and maintain
performance.

[Link]
What strategies can be employed to manage the
complexity of revisions in APIs effectively?
Answer:Effective strategies for managing revision
complexity include clearly documenting the revision process,
ensuring consistent revision creation strategies across
resources, leveraging custom methods for tasks like listing
and deleting revisions, and designing an intuitive interface
for users to interact with revisions without overwhelming
them with unnecessary complexity.

[Link]
Why is it crucial to support deletion of specific revisions
in an API?
Answer:Supporting the deletion of specific revisions is
crucial for maintaining privacy and data hygiene, especially
when sensitive information has been inadvertently stored in a
resource. Without such functionality, removing sensitive
information would be ineffective, as it could still exist in
prior revisions, potentially leading to compliance or security
issues.

[Link]
How should an API be structured to retrieve specific
revisions of a resource?
Answer:An API should utilize a clear and simple method for
retrieving specific revisions of a resource, such as
incorporating a special separator (e.g., '@') to distinguish
between the resource ID and the revision ID in the request.
This allows users to access past states of the resource easily
without complicating the standard retrieval methods.

[Link]
Why is it important to have different custom methods for
deleting revisions versus deleting resources in APIs?
Answer:Having distinct custom methods for deleting
revisions versus deleting entire resources helps prevent user
errors that could lead to accidental data loss. Clearly
delineating these functionalities reinforces the importance of
careful data management, ensuring that users can perform
operations without the risk of unintended consequences.
Chapter 30 | 29 Request retrial| Q&A
[Link]
What should clients consider when deciding to retry a
failed API request?
Answer:Clients should distinguish between types of
errors. Generally, 400-level errors (like 400 Bad
Request or 403 Forbidden) indicate issues with the
request itself, suggesting retries are futile. In
contrast, 500-level errors (like 500 Internal Server
Error or 503 Service Unavailable) may suggest
transient issues, hence retries could be worthwhile.

[Link]
Why is exponential back-off considered an effective
strategy for retrying API requests?
Answer:Exponential back-off helps manage the timing of
retries by increasing the wait time exponentially after each
failure (e.g., 1s, 2s, 4s, etc.). This approach reduces the
likelihood of overwhelming the API server, particularly
useful in peak traffic scenarios, thus avoiding bottlenecks.

[Link]
How does random jitter help prevent stampeding herds in
API requests?
Answer:Introducing random jitter means adding a random
amount of time to the retry wait period, which helps stagger
the retry attempts from multiple clients. Without jitter, clients
retrying at the same interval can flood the server when it
becomes available, causing a stampede.

[Link]
When is it appropriate to use the Retry-After HTTP
header and what format should it take?
Answer:The Retry-After header is useful when the API
server can indicate a specific duration for which the client
should wait before retrying the request. It should generally be
specified as a duration in seconds rather than a specific date,
as this prevents potential issues with time synchronization
between server and client.

[Link]
What are the trade-offs associated with relying on clients
to follow retry instructions?
Answer:While relying on clients to follow specific
instructions may result in fewer retries and more efficient
resource use, it also raises concerns as the server cannot
ensure compliance. Clients may not implement retry policies
correctly, leading to inefficiencies or errors.
Chapter 31 | 30 Request authentication| Q&A
[Link]
What are the key requirements for successful request
authentication?
Answer:1. Proof of Origin: Ensures that a request
comes from a known source without uncertainty.
2. Integrity: Ensures that the request content has not
been tampered with during transit.
3. Nonrepudiation: Prevents the requester from
denying that they sent the request.

[Link]
How does digital signature technology meet the
requirements for API request authentication?
Answer:Digital signatures use a pair of keys (public and
private) where:
- The private key is used to generate a signature, ensuring
that only the holder of the private key can create it.
- The public key allows others to verify that the signature
was indeed created using the corresponding private key, thus
confirming origin and integrity.

[Link]
Why is it important to include the HTTP method, host,
and path in the request fingerprint?
Answer:Including these elements in the request fingerprint
helps ensure that the specific request being made is
accurately recorded and verified. If any of these components
were altered, the fingerprint would change, indicating
tampering, which is crucial for maintaining integrity.

[Link]
What challenges arise from different serialization
methods when calculating a digital signature?
Answer:Serialization may vary between character encodings
and formats (e.g., JSON). The same semantic message can
have different byte representations, leading to signature
verification failures if differing methods are used to serialize
the request content.

[Link]
How can nonrepudiation be ensured with an asymmetric
credential system?
Answer:By ensuring that the credential used to sign requests
(private key) is never shared with the API server, each user's
signature uniquely identifies them. If a request is signed with
their private key, they cannot later deny having sent it, as
only they have access to that private key.

[Link]
What is the role of a request fingerprint in request
signing?
Answer:The request fingerprint acts as a digest that uniquely
represents the request. It combines crucial elements of the
request (method, path, headers) ensuring that any changes in
the request will invalidate the signature, thus confirming both
integrity and origin.

[Link]
Why might a simpler authentication method, like HMAC,
be preferred in some scenarios over digital signatures?
Answer:While digital signatures are more secure, they are
computationally intensive and may not be necessary for all
applications. In cases where nonrepudiation is not critical, or
the computational load is a significant concern, HMAC with
shared secrets could be more efficient.

[Link]
In what ways can digital signatures address replay
attacks?
Answer:Digital signatures can include timestamps or nonce
values in the signed data to ensure that requests are fresh and
have not been reused. If a request is too old, it can be
rejected, thus preventing a replay attack.

[Link]
How does the system establish a unique identity for a user
during the registration process?
Answer:During registration, the user submits their public key
as part of the credential exchange, which the API server
associates with a unique identifier, thus creating a secure
identity without needing traditional credentials like username
and password.

[Link]
What key factors must be considered while verifying a
request's signature?
Answer:To verify a signature, it’s essential to:
- Ensure the digest header accurately reflects the content of
the request.
- Recompute the fingerprint using the signature metadata.
- Use the correct public key corresponding to the unique
identifier to verify the signature against the computed
fingerprint.
API Design Patterns Quiz and Test
Check the Correct Answer on Bookey Website

Chapter 1 | API Design Patterns| Quiz and Test

[Link] book 'API Design Patterns' primarily focuses
on theoretical aspects of API design rather than
practical guidelines.
[Link] Skeet believes that well-designed APIs can
significantly enhance user experience and reduce
frustration.
[Link] book is organized into four parts including 'General
API Design Principles', 'Design Patterns', and 'Safety and
Security'.
Chapter 2 | 1 Introduction to APIs| Quiz and Test
[Link] are primarily designed for local usage and
users can control changes to the API.
[Link]-oriented APIs focus on managing individual
actions rather than overall resources.
[Link] an API to be considered 'good', it must be operational,
expressive, and predictable.
Chapter 3 | 2 Introduction to API design patterns|
Quiz and Test
[Link] design patterns are established solutions to
uncommon problems in API development.
[Link] design patterns provide a structured approach that
mitigates risks and complexities in API design.
[Link] chapter argues that design patterns are not necessary
for enhancing API robustness and maintainability.
Chapter 4 | 3 Naming| Quiz and Test
[Link] in software engineering are only important
after code is compiled.
[Link] names should be complex to convey their meaning
effectively.
[Link] greatly influences the meaning of a name in API
design.
Chapter 5 | 4 Resource scope and hierarchy| Quiz
and Test
[Link] layout refers to the arrangement of
resources within an API, including how they relate
to one another. True or False?
[Link]-to-many relationships in resource layouts mean that
one resource can reference only one other resource. True or
False?
[Link] hierarchies in resource relationships are always
beneficial and should be implemented in all API designs.
True or False?
Chapter 6 | 5 Data types and defaults| Quiz and Test
[Link] API design, it is crucial to consider types that
allow interaction across various programming
languages.
[Link] should primarily use negative flags to reduce
cognitive load.
[Link] should be treated as atomic pieces of data and
modifications to lists should only alter individual elements.
Chapter 7 | 6 Resource identification| Quiz and Test
[Link] must be unique within a defined context
to avoid identification issues.
[Link] are the only suitable format for creating effective
identifiers in APIs.
[Link] should be permanent and not change
post-assignment to ensure consistent resource
identification.
Chapter 8 | 7 Standard methods| Quiz and Test
[Link] methods in API design include actions
such as GET, LIST, CREATE, UPDATE,
DELETE, and REPLACE.
[Link] resources in an API must support every standard
method to ensure predictability.
[Link] methods should avoid side effects to minimize the
risk of unintended consequences.
Chapter 9 | 8 Partial updates and retrievals| Quiz
and Test
[Link] retrievals in API design are only applicable
 to small resources and do not provide benefits for
large resources.
[Link] masks are a recommended tool for specifying which
fields to retrieve or update in a resource.
[Link] should allow addressing repeated fields by index to
optimize partial updates and retrievals.
Chapter 10 | 9 Custom methods| Quiz and Test
[Link] methods in API design can include actions
with side effects, unlike standard methods.
[Link] standard HTTP methods will always accommodate
actions such as sending emails or performing state changes
without the need for custom methods.
[Link] methods primarily utilize the GET HTTP verb to
ensure resources are fetched without side effects.
Chapter 11 | 10 Long-running operations| Quiz and
Test
[Link]-Running Operations (LROs) are designed
for managing immediate and synchronous API
calls effectively.
[Link] include mechanisms for tracking progress, errors,
and allows operations to be paused and resumed.
[Link] should be nested within the operations they pertain
to for better management and efficiency.
Chapter 12 | 11 Rerunnable jobs| Quiz and Test
[Link] jobs can simplify management and
 enhance control over access permissions in APIs.
2.A job's 'run' method can accept multiple parameters to
execute a job with various configurations.
[Link] jobs are only useful for asynchronous method
execution in APIs.
Chapter 13 | 12 Singleton sub-resources| Quiz and
Test
1.A singleton sub-resource is designed to exist
independently from its parent resource at the root
level of the API hierarchy.
[Link] components often need to be separated from parent
resources to enhance performance and manage complexity
effectively.
[Link] interaction with both the parent resource and its
singleton sub-resource simultaneously is possible without
limitations.
Chapter 14 | 13 Cross references| Quiz and Test
[Link] fields in APIs should typically have
names that end with 'ID' to convey the type and
purpose of the resource being referenced.
[Link] that hold copies of resource data should include the
suffix 'ID' to indicate they are references to other resources.
[Link] in APIs are always reliable and maintained
properly regardless of resource deletions.
Chapter 15 | 14 Association resources| Quiz and Test
[Link] API resource relationships are typically
unidirectional and simple.
[Link] resources should allow for users to be
associated with the same group multiple times without
restrictions.
[Link] an association resource is created, the core identifiers
should remain changeable over time.
Chapter 16 | 15 Add and remove custom methods|
Quiz and Test
[Link] add and remove methods provide a way to
manage many-to-many relationships directly
without handling association resources.
[Link] custom methods allows for the storage of metadata
related to resource relationships.
[Link] this chapter, the add and remove methods serve as
shortcuts to create or delete associations while exposing
intricate details.
Chapter 17 | 16 Polymorphism| Quiz and Test
[Link] allows objects to utilize common
interfaces while minimizing implementation
details.
[Link] a polymorphic resource is advisable when the
resource types do not show commonality.
[Link] methods are preferable over polymorphic
resources to maintain future flexibility.
Chapter 18 | 17 Copy and move| Quiz and Test
[Link] in APIs should never need to be
renamed or relocated.
[Link] copying, user-specified identifiers should not be
treated like standard create methods.
[Link] copy and move operations in APIs is always
recommended as they simplify resource management.
Chapter 19 | 18 Batch operations| Quiz and Test
[Link] operations in APIs allow users to
manipulate multiple resources in bulk, enhancing
efficiency.
[Link] in batch operations means that if any operation
within the batch fails, all other operations will still succeed.
[Link] methods must be designed to operate on individual
resources rather than collections.
Chapter 20 | 19 Criteria-based deletion| Quiz and
Test
[Link] custom purge method allows users to delete
resources without needing to know their unique
identifiers.
[Link] purge method, when misconfigured, can lead to
catastrophic results without user awareness.
[Link] purge method defaults to executing deletions
immediately without requiring user confirmation.
Chapter 21 | 20 Anonymous writes| Quiz and Test
[Link] chapter suggests that the `write` method
 returns identifiable resources after data insertion.
[Link] to the chapter, users should expect immediate
visibility of their data entries when using the `write`
method.
[Link] chapter emphasizes that the design approach is
specifically suited for analytical data rather than
transactional data.
Chapter 22 | 21 Pagination| Quiz and Test
[Link] in APIs allows users to retrieve all data
in one request without overwhelming the system.
[Link] cursor-based pagination helps to supply a current
chunk of data along with a token for retrieving the next
one.
[Link] a total count of results in pagination responses is
always advisable for better performance.
Chapter 23 | 22 Filtering| Quiz and Test
[Link] in API design allows users to retrieve a
specific subset of resources based on defined
criteria.
[Link] chapter recommends the client to handle filtering
instead of the server to ensure efficient resource fetching.
[Link] use of structured query interfaces is always more
beneficial than string-based queries for filtering in APIs.
Chapter 24 | 23 Importing and exporting| Quiz and
Test
[Link] managing user data should enable inefficient
 resource transfer directly to and from the external
storage system.
[Link] chapter emphasizes the importance of using tightly
coupled configuration structures to maximize flexibility
and reusability.
[Link] and export patterns are specific to data movement
and can handle multiple resource types and complex
business logic effectively.
Chapter 25 | 24 Versioning and compatibility| Quiz
and Test
[Link] is a mechanism that allows API
designers to evolve their APIs over time while
minimizing disruptions to users.
[Link] means that code written against one version
of an API may not necessarily work with another version.
[Link] compatibility means that changes can be made
to an API without affecting existing users' functionalities.
Chapter 26 | 25 Soft deletion| Quiz and Test
[Link] deletion in APIs allows for resources to be
permanently removed immediately after deletion.
[Link] soft deletion involves using a Boolean flag
to indicate if a resource is deleted or not.
[Link] method for undeleting a resource should provide an
error response if the resource is hard-deleted.
Chapter 27 | 26 Request deduplication| Quiz and
Test
[Link] identifiers are crucial to prevent duplicate
requests in web APIs.
[Link] responses can always be relied on to provide
up-to-date information.
3.A poor user-generated request ID can lead to collisions,
which need to be managed in API design.
Chapter 28 | 27 Request validation| Quiz and Test
[Link] `validateOnly` field is essential for pre-request
validation in APIs, specifically for unsafe methods.
[Link] requests with the `validateOnly` flag always
guarantees accurate responses even when dealing with
external dependencies.
[Link] validation requests is merely a convenience and
not necessary for API functionality.
Chapter 29 | 28 Resource revisions| Quiz and Test
[Link] revisions only allow for tracking the
current state of resources.
[Link] revisions can be done both implicitly and
explicitly, with implicit being the preferred method.
[Link] a resource to a previous state does not maintain
the historical record of revisions.
Chapter 30 | 29 Request retrial| Quiz and Test
[Link] errors are never retriable, regardless of
the error code.
[Link] an exponential back-off algorithm helps
 manage timing for retries effectively.
[Link] jitter should not be used in retry strategies as it
complicates the process unnecessarily.
Chapter 31 | 30 Request authentication| Quiz and
Test
[Link] signatures are primarily used to ensure the
integrity, origin authenticity, and nonrepudiation
of API requests.
[Link] origin of an API request can be confirmed using
physical identifiers of the user.
[Link] signatures make use of symmetric credentials,
where the private key is shared with the API server for
authentication.