A Field Guide to API Design

Common screening tests include chlamydia and gonorrhea tests, often using urine or a swab. A swab may be taken from the vagina, cervix, throat or rectum, depending on anatomy and the sites exposed. A urine sample does not check every body site, so explain which kinds of contact you want the screening to cover. In some settings, self-collected swabs are available.

Load Balancing: Periodic jobs should be safe to run twice, because they will be. Load Balancing: You rarely need a new component to fix a boundary problem. Load Balancing: The signal you want is often already logged, just not aggregated.

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

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

The interesting number is not the average, it is the 99th percentile. That applies to release process as well. In practice, release process 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 release process.

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

Talking about boundaries can make intimacy clearer and safer, but it may feel awkward at first. A boundary is a limit or condition that describes what you are comfortable with; it is not a demand that another person must feel the same way. A step-by-step conversation can help both partners understand what is welcome, what is not, and how to respond when feelings or circumstances change.

Data Pipelines: Configurations should be reviewable in a diff, not only in a console. The best time to add an index is before the table gets large. That applies to data pipelines as well. In practice, data pipelines behaves differently: Failures are usually correlated, so plan for the shared dependency.

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.

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

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

Release Process: Periodic jobs should be safe to run twice, because they will be. Release Process: You rarely need a new component to fix a boundary problem. Release Process: The signal you want is often already logged, just not aggregated.

For crawl budget, the constraint matters more than the feature list. The first thing to settle is the failure mode, not the happy path. Teams working on crawl budget 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 crawl budget.

Edge Caching: 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. Edge Caching: Track the denominator as carefully as the numerator.

In practice, search indexing behaves differently: Periodic jobs should be safe to run twice, because they will be. You rarely need a new component to fix a boundary problem. The same reasoning holds for search indexing. For search indexing, the constraint matters more than the feature list. The signal you want is often already logged, just not aggregated.

Teams working on schema migration usually discover this the hard way. You can often replace a coordination problem with an idempotency key. Anything that grows without a bound will eventually hit one. This is most visible in schema migration. Consider schema migration specifically. Documentation that is not tested tends to describe the previous version.

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

Talk about privacy, too. Clarify whether intimate messages or images may be saved, shown to someone else, or shared online. Do not assume that permission to create or send an image includes permission to distribute it. Laws concerning intimate images differ across countries, and sharing without consent may have serious consequences. If you do not want an image made or shared, state that plainly.

Teams working on crawl budget usually discover this the hard way. You can often replace a coordination problem with an idempotency key. Anything that grows without a bound will eventually hit one. This is most visible in crawl budget. Consider crawl budget specifically. Documentation that is not tested tends to describe the previous version.

Load Balancing: A queue smooths spikes but also hides how far behind you are. Retries without jitter turn a small outage into a large one. That applies to load balancing as well. In practice, load balancing behaves differently: Separating the reads from the writes buys room to change either side.

For observability, the constraint matters more than the feature list. A queue smooths spikes but also hides how far behind you are. Teams working on observability 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 observability.

Use statements about your own needs rather than trying to guess your partner’s intentions. You might say, “I’m comfortable with this, but not with that,” or, “I need us to stop if I say pause.” Be specific about what you mean by words such as “slow down” or “check in.” Ask your partner what they are comfortable with, and leave room for an answer without interrupting or arguing.

A design that cannot be rolled back is a design that cannot be changed safely. The same reasoning holds for queue design. For queue design, the constraint matters more than the feature list. Latency budgets are easier to defend when every hop has a stated ceiling. Teams working on queue design usually discover this the hard way. Caching helps only until the invalidation rules become the bottleneck.

Consider crawl budget specifically. A design that cannot be rolled back is a design that cannot be changed safely. Crawl Budget: Latency budgets are easier to defend when every hop has a stated ceiling. Caching helps only until the invalidation rules become the bottleneck. That applies to crawl budget as well.