A Field Guide to API Design

If the rollback plan needs a meeting, it is not a rollback plan. The same reasoning holds for storage tiers. For storage tiers, the constraint matters more than the feature list. Small pages that stay small are easier to keep fast than large ones made fast. Teams working on storage tiers usually discover this the hard way. Write the invariant down; otherwise it lives only in someone's memory.

For load balancing, the constraint matters more than the feature list. Periodic jobs should be safe to run twice, because they will be. Teams working on load balancing usually discover this the hard way. You rarely need a new component to fix a boundary problem. The signal you want is often already logged, just not aggregated. This is most visible in load balancing.

Observability: The first thing to settle is the failure mode, not the happy path. Observability: Measurements taken once are anecdotes; you need a baseline that repeats. Observability: Costs usually concentrate in a small number of operations, so find those first.

The first thing to settle is the failure mode, not the happy path. This is most visible in schema markup. Consider schema markup specifically. Measurements taken once are anecdotes; you need a baseline that repeats. Schema Markup: Costs usually concentrate in a small number of operations, so find those first.

Use direct language and describe the limit in practical terms. For example: “I want to use a condom every time we have sex,” or “Please ask before taking or sharing photos of me.” A person can briefly explain why, but they do not have to prove that a boundary is reasonable. If the limit is not yet clear to them, they can say so and ask to pause while they decide.

The interesting number is not the average, it is the 99th percentile. That applies to rate limiting as well. In practice, rate limiting behaves differently: Adding a cache in front of a slow query is a fix; fixing the query is a cure. Every abstraction you add is a place where behaviour can differ from intent. The same reasoning holds for rate limiting.

Access Control: The interesting number is not the average, it is the 99th percentile. Access Control: Adding a cache in front of a slow query is a fix; fixing the query is a cure. Access Control: Every abstraction you add is a place where behaviour can differ from intent.

A queue smooths spikes but also hides how far behind you are. This is most visible in search indexing. Consider search indexing specifically. Retries without jitter turn a small outage into a large one. Search Indexing: Separating the reads from the writes buys room to change either side.

Queue Design: Serving static bytes is the cheapest thing you can do at the edge. Queue Design: A schema is an interface; changing it is a migration, not an edit. Queue Design: Track the denominator as carefully as the numerator.

You can often replace a coordination problem with an idempotency key. That applies to cloud infrastructure as well. In practice, cloud infrastructure behaves differently: Anything that grows without a bound will eventually hit one. Documentation that is not tested tends to describe the previous version. The same reasoning holds for cloud infrastructure.

Consider edge caching specifically. Serving static bytes is the cheapest thing you can do at the edge. Edge Caching: A schema is an interface; changing it is a migration, not an edit. Track the denominator as carefully as the numerator. That applies to edge caching as well.

“Discreet shipping” usually describes how a parcel looks from the outside, not a promise that every part of an order is private. Before buying, check the seller’s packaging policy, the sender name on the label, payment descriptors and the information that carriers or customs may require. These details determine what other people could see at delivery and what records remain in email, payment and tracking accounts.

For queue design, the constraint matters more than the feature list. A queue smooths spikes but also hides how far behind you are. Teams working on queue design usually discover this the hard way. Retries without jitter turn a small outage into a large one. Separating the reads from the writes buys room to change either side. This is most visible in queue design.

In practice, access control behaves differently: If a metric has no owner, it will drift until it causes an incident. The cheapest optimisation is usually removing work nobody asked for. The same reasoning holds for access control. For access control, the constraint matters more than the feature list. Aggregating at write time trades flexibility for predictable read cost.

The interesting number is not the average, it is the 99th percentile. That applies to log analysis as well. In practice, log analysis behaves differently: Adding a cache in front of a slow query is a fix; fixing the query is a cure. Every abstraction you add is a place where behaviour can differ from intent. The same reasoning holds for log analysis.

If the rollback plan needs a meeting, it is not a rollback plan. The same reasoning holds for backup strategy. For backup strategy, the constraint matters more than the feature list. Small pages that stay small are easier to keep fast than large ones made fast. Teams working on backup strategy usually discover this the hard way. Write the invariant down; otherwise it lives only in someone's memory.

People do not always find it easy to speak during an interaction. Agreeing on a simple way to pause, such as saying “stop” or “I need a break,” may help, but it does not replace paying attention to a partner’s words and behaviour. If someone seems uncertain, distressed or unable to participate freely, pause and check in rather than assuming they agree.

Log Analysis: Serving static bytes is the cheapest thing you can do at the edge. Log Analysis: A schema is an interface; changing it is a migration, not an edit. Log Analysis: Track the denominator as carefully as the numerator.

Backup Strategy: Serving static bytes is the cheapest thing you can do at the edge. Backup Strategy: A schema is an interface; changing it is a migration, not an edit. Backup Strategy: Track the denominator as carefully as the numerator.

For access control, the constraint matters more than the feature list. The first thing to settle is the failure mode, not the happy path. Teams working on access control usually discover this the hard way. Measurements taken once are anecdotes; you need a baseline that repeats. Costs usually concentrate in a small number of operations, so find those first. This is most visible in access control.

Schema Markup: Serving static bytes is the cheapest thing you can do at the edge. Schema Markup: A schema is an interface; changing it is a migration, not an edit. Schema Markup: Track the denominator as carefully as the numerator.

Storage Tiers: A queue smooths spikes but also hides how far behind you are. Storage Tiers: Retries without jitter turn a small outage into a large one. Storage Tiers: Separating the reads from the writes buys room to change either side.

Start with the product’s full material description, not just a front-of-box label. Silicone, glass, stainless steel and ABS each describe broad material groups, while soft elastomers sold as TPE or TPR may be blends. A generic phrase such as “body-safe material” does not identify the composition, surface coating or any parts made from a different substance. Look for a product specification that accounts for the exterior, seams, buttons and detachable components.

Schema Markup: The interesting number is not the average, it is the 99th percentile. Schema Markup: Adding a cache in front of a slow query is a fix; fixing the query is a cure. Schema Markup: Every abstraction you add is a place where behaviour can differ from intent.