English for API Design Reviews
Master the vocabulary and diplomatic phrasing for discussing endpoint design, versioning, and contract decisions in an API design review.
An API design review is a different kind of conversation than a regular code review — the decisions being discussed will be much harder to change once external consumers depend on them, so the vocabulary needs to be precise about tradeoffs, not just correctness. Being able to say exactly what’s wrong with a proposed contract, and why, moves the conversation forward far faster than a vague “this doesn’t feel right.”
Key Vocabulary
Contract (API contract) The formal agreement between an API and its consumers about request and response shapes, status codes, and behavior — the thing a design review is really evaluating. Example: “Changing this field’s type would break the contract for every existing consumer, so we need a versioning strategy rather than modifying it in place.”
Idempotency The property of an API operation producing the same result regardless of how many times it’s called with the same input, critical for operations that clients might retry after a network failure. Example: “This endpoint isn’t idempotent — calling it twice with the same request creates two orders instead of one, which will bite us the moment a client retries after a timeout.”
Backward compatibility The property of a new API version continuing to work correctly for consumers built against an earlier version, without requiring them to change anything. Example: “Adding this optional field is backward compatible, but removing that other field isn’t — existing clients that depend on it would break silently.”
Breaking change Any modification to an API’s contract that could cause existing, correctly-written consumers to fail or behave incorrectly. Example: “Renaming this field is a breaking change even though the data itself is unchanged — every consumer parsing the old field name would suddenly get nulls.”
Pagination A strategy for returning large result sets in smaller, sequential chunks rather than all at once, typically using either offset-based or cursor-based approaches. Example: “We should use cursor-based pagination here instead of offset-based, since offset pagination gets inconsistent results if items are inserted or deleted between page requests.”
Resource (RESTful resource) A named entity exposed by an API, typically represented as a noun in the URL path, with standard HTTP methods representing operations on it. Example: “This endpoint is modeled as an action rather than a resource — let’s reconsider whether it should be expressed as a POST to a resource collection instead.”
Versioning strategy The overall approach an API takes to introducing breaking changes over time, such as URL-based versioning, header-based versioning, or additive-only evolution. Example: “Our versioning strategy is additive-only wherever possible, so we only introduce a new major version when a genuinely breaking change is unavoidable.”
Error contract The consistent, documented shape of error responses across an API, including status codes and error body structure, so consumers can handle failures predictably. Example: “This endpoint returns a different error shape than the rest of the API — we should align it with our standard error contract before this ships.”
Common Phrases
In design reviews:
- “This endpoint isn’t idempotent, and I think that’s a real risk given how often clients on mobile networks retry failed requests.”
- “Adding this field is backward compatible, but I want to flag that removing the deprecated field next quarter will still be a breaking change for anyone still using it.”
- “The pagination approach here will produce duplicate or skipped items under concurrent writes — should we switch to a cursor-based approach instead?”
In pull request or proposal comments:
- “This looks good functionally, but the error contract doesn’t match the rest of the API — can we align the error shape before merging?”
- “I’d like to see this modeled as a resource with standard HTTP verbs rather than a single action endpoint, mainly for consistency with the rest of our API surface.”
- “This is a breaking change for existing consumers — do we have a plan for versioning it, or is this going out as part of a coordinated major release?”
In discussions with API consumers:
- “We’re planning to deprecate this field over the next two release cycles — is there anything blocking you from migrating to the replacement field before then?”
- “This new version is backward compatible for everyone currently on v2, so no action is needed unless you want the new capability.”
- “We’d like feedback on this proposed contract before it’s finalized — does the pagination cursor format work cleanly with your existing client code?”
Phrases to Avoid
Saying “this doesn’t feel right” without naming the specific issue. Say instead: “this endpoint isn’t idempotent, which is risky given retry behavior on flaky networks” — vague discomfort doesn’t give the author anything actionable to change.
Saying “just add a version number” without a strategy. Say instead: “what’s our versioning strategy here — URL-based, header-based, or additive-only evolution?” — jumping straight to a version bump without an explicit strategy tends to produce inconsistent versioning across an API surface over time.
Saying “it’s a small change” for something that alters the contract. Say instead: “this changes the response shape, which is a breaking change regardless of how small the diff looks” — contract changes should be evaluated by their effect on consumers, not by the size of the code diff.
Quick Reference
| Term | How to use it |
|---|---|
| contract | ”Changing this field’s type breaks the contract for existing consumers.” |
| idempotency | ”This endpoint isn’t idempotent, which is risky under client retries.” |
| backward compatibility | ”Adding an optional field preserves backward compatibility.” |
| breaking change | ”Renaming this field is a breaking change even if the data is the same.” |
| pagination | ”Cursor-based pagination avoids duplicate or skipped items.” |
| versioning strategy | ”Our strategy favors additive-only changes over frequent major bumps.” |
Key Takeaways
- Name the specific contract issue (idempotency, breaking change, pagination consistency) rather than expressing vague discomfort with a proposed design.
- Evaluate changes by their effect on existing consumers, not by how small the code diff looks — a one-line rename can still be a breaking change.
- Agree on a versioning strategy explicitly before a breaking change ships, rather than defaulting to an ad hoc version bump.
- Recommend cursor-based pagination over offset-based when result sets can change between page requests, and explain why in terms of consistency.
- Keep error response shapes consistent across an API’s surface, and call out mismatches in review just as you would any other contract inconsistency.