A Field Guide to API Design

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

Content Delivery: If the rollback plan needs a meeting, it is not a rollback plan. Content Delivery: Small pages that stay small are easier to keep fast than large ones made fast. Content Delivery: Write the invariant down; otherwise it lives only in someone's memory.

Crawl Budget: You can often replace a coordination problem with an idempotency key. Crawl Budget: Anything that grows without a bound will eventually hit one. Crawl Budget: Documentation that is not tested tends to describe the previous version.

A boundary can change as a person’s comfort, health, relationship or circumstances change. Checking in does not mean asking for repeated permission in a way that becomes pressure; it means making space for an honest answer. Agree on a simple way to pause, such as a clear word or phrase, and treat it as a stop signal. If someone changes their mind, the other person should stop without demanding an explanation.

Serving static bytes is the cheapest thing you can do at the edge. That applies to schema markup as well. In practice, schema markup behaves differently: A schema is an interface; changing it is a migration, not an edit. Track the denominator as carefully as the numerator. The same reasoning holds for schema markup.

If the rollback plan needs a meeting, it is not a rollback plan. That applies to access control as well. In practice, access control behaves differently: Small pages that stay small are easier to keep fast than large ones made fast. Write the invariant down; otherwise it lives only in someone's memory. The same reasoning holds for access control.

Talking about boundaries can make expectations clearer in a relationship, including around physical contact, sex, privacy and communication. A useful conversation is specific and voluntary: each person can say what feels acceptable, ask questions and change their mind without being pressured.

Queue Design: A design that cannot be rolled back is a design that cannot be changed safely. Queue Design: Latency budgets are easier to defend when every hop has a stated ceiling. Queue Design: Caching helps only until the invalidation rules become the bottleneck.

Separate the outer parcel from the product’s retail packaging. A seller may place a branded product box inside a plain shipping carton, but that does not establish that the carton is opaque, sealed against viewing, or free of paperwork. Check whether packing slips, invoices or promotional inserts are included. If the answer is not published, do not assume that a plain exterior also means the contents are hidden from the recipient who opens it or from anyone with access to the delivery.

Rate Limiting: If a metric has no owner, it will drift until it causes an incident. Rate Limiting: The cheapest optimisation is usually removing work nobody asked for. Rate Limiting: Aggregating at write time trades flexibility for predictable read cost.

Backup Strategy: If a metric has no owner, it will drift until it causes an incident. Backup Strategy: The cheapest optimisation is usually removing work nobody asked for. Backup Strategy: Aggregating at write time trades flexibility for predictable read cost.

Consider cloud infrastructure specifically. The interesting number is not the average, it is the 99th percentile. Cloud Infrastructure: 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. That applies to cloud infrastructure as well.

Release Process: You can often replace a coordination problem with an idempotency key. Release Process: Anything that grows without a bound will eventually hit one. Release Process: Documentation that is not tested tends to describe the previous version.

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

In practice, release process behaves differently: The first thing to settle is the failure mode, not the happy path. Measurements taken once are anecdotes; you need a baseline that repeats. The same reasoning holds for release process. For release process, the constraint matters more than the feature list. Costs usually concentrate in a small number of operations, so find those first.

Load Balancing: Configurations should be reviewable in a diff, not only in a console. Load Balancing: The best time to add an index is before the table gets large. Load Balancing: Failures are usually correlated, so plan for the shared dependency.

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.

Separate a boundary from a preference where you can. A preference describes something you like or would choose; a boundary describes what you are not willing to do, or what you need in order to feel comfortable. Both are useful information, but a boundary should not be treated as an opening offer to negotiate. You can say, “I’m not comfortable with that,” without supplying a detailed reason.

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

Periodic jobs should be safe to run twice, because they will be. This is most visible in backup strategy. Consider backup strategy specifically. You rarely need a new component to fix a boundary problem. Backup Strategy: The signal you want is often already logged, just not aggregated.

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

Teams working on data pipelines usually discover this the hard way. The interesting number is not the average, it is the 99th percentile. Adding a cache in front of a slow query is a fix; fixing the query is a cure. This is most visible in data pipelines. Consider data pipelines specifically. Every abstraction you add is a place where behaviour can differ from intent.

You can often replace a coordination problem with an idempotency key. The same reasoning holds for rate limiting. For rate limiting, the constraint matters more than the feature list. Anything that grows without a bound will eventually hit one. Teams working on rate limiting usually discover this the hard way. Documentation that is not tested tends to describe the previous version.

Packaging is only one part of the record. A card or bank statement may show a payment descriptor that differs from the storefront name, and an order confirmation may name the seller in its subject line or sender address. Shipping alerts can appear on a shared email account, text-message preview or carrier account. Review which contact details are attached to checkout and whether the carrier offers delivery alerts. Do not count on a “discreet” parcel to hide an order from someone who can see those accounts or payment records.