English for API Design Reviews

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

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.

Navigating Nuances: Refining Your Approach with Targeted Vocabulary

API design reviews can feel incredibly high stakes, especially when dealing with complex architectural decisions. Beyond simply stating your intentions, successful communication hinges on using precise language that clearly conveys intent, acknowledges potential concerns, and invites constructive feedback. For non-native English speakers, this often translates to a particular anxiety around expressing technical ideas confidently in a professional setting. Let’s focus on building a more robust vocabulary specifically geared towards these situations – not just the basics of “good” or “bad,” but nuanced terms that demonstrate understanding and proactive engagement.

One area where many developers struggle is articulating the reasoning behind design choices. Instead of simply saying “This endpoint needs to be faster,” consider phrases like, “I’ve prioritized this endpoint’s performance due to anticipated high traffic volumes based on recent usage data,” or “Optimizing this endpoint aligns with our team’s current focus on reducing latency for critical user flows.” Similarly, when discussing versioning – a notoriously tricky topic – move beyond “we need to version” and instead utilize terms like “semantic versioning,” “major/minor/patch changes,” or “introducing backward compatibility considerations.” These specific terms demonstrate an understanding of the underlying principles.

Furthermore, learning how to frame potential concerns diplomatically is crucial. Rather than immediately reacting defensively to a comment like, “This endpoint feels overly complex,” try responding with something like, “Thank you for raising that point; I appreciate the opportunity to clarify my reasoning. I’ve been mindful of complexity during design and believe this structure allows for future extensibility while maintaining clarity.” Or, in a Slack conversation, instead of saying “That’s wrong,” consider “Could we explore alternative approaches? Perhaps [suggest a specific alternative] would achieve a similar outcome with reduced cognitive load?”

Finally, remember the importance of acknowledging uncertainty. It’s perfectly acceptable – and demonstrates intellectual honesty – to say, “I’m still evaluating the best approach for this particular scenario and welcome any insights you have.” Avoid absolute statements like “This is the correct way” which can immediately put others on the defensive. Focus instead on collaborative exploration and shared understanding. Building these specific phrases into your vocabulary will significantly improve your ability to navigate API design reviews with confidence and contribute effectively to technical discussions.