API Design Discussions: Phrases for Contract Negotiations
5 exercises on idempotency, versioning, contracts, and pagination language. Choose the most natural and professional option.
0 / 5 completed
1 / 5
You're reviewing an endpoint that creates a resource and could be called twice accidentally. What do you say?
KEY PHRASE: "This endpoint should be idempotent" Idempotency is the precise API design term: repeated calls with the same input produce the same output and have no additional side effects. It's a fundamental REST principle, especially for PUT and DELETE. Mentioning it by name signals fluency in API design. Real examples: "Make the POST idempotent using a client-generated idempotency key in the header"; "DELETE should be idempotent by definition — deleting an already-deleted resource should return 404, not 500." Options A and D avoid the technical term. Option B is accurate but vague — "somehow" does no design work. In API reviews, naming concepts precisely speeds up the discussion.
2 / 5
You're proposing to add a version prefix to avoid breaking existing API consumers. Which is best?
KEY PHRASE: "We need to version this to avoid breaking consumers" This connects the technical action (versioning) to the business reason (not breaking existing integrations). "Consumers" is the correct API term for callers or clients — it's more precise than "users" in an API context. Suggesting a specific path convention (/api/v2/) makes the proposal actionable. Real examples: "Version this as /v2 to give consumers a migration window before we deprecate v1"; "We should version the response schema to avoid breaking existing consumers who parse the fields." Options B-D are informal or incomplete — they don't explain the reason or use the standard vocabulary.
3 / 5
You're explaining what the API guarantees to callers in a design review. What's the clearest phrasing?
KEY PHRASE: "The contract is: a 200 with..., a 404 if..., and a 422 for..." "The contract" is the precise term for what an API guarantees to its consumers — specific inputs, outputs, and error codes. Listing the response codes explicitly (200/404/422) shows completeness and signals that the design is deliberate, not ad hoc. Real examples: "Our contract: 201 on create, 409 on conflict, never a 500 from business logic — only from infrastructure"; "The contract is stable — these fields will not be removed without a major version bump." Options A-C are softer and don't invoke the formal concept of a binding API contract.
4 / 5
A list endpoint could return thousands of records. How do you propose a better approach?
KEY PHRASE: "I'd recommend cursor-based pagination for this resource — it's more efficient at scale than offset" This names the pagination strategy (cursor-based vs offset), explains the technical reason (efficiency at scale), and uses the correct API design vocabulary. Cursor pagination avoids the consistency and performance problems of OFFSET-based pagination at high page numbers. Real examples: "Use cursor pagination — offset breaks at high page numbers when data is being inserted concurrently"; "I'd recommend keyset pagination here given the expected data volume and sort requirements." Options A, C, and D are too generic — they don't specify the mechanism or justify the choice, which is the whole point of a design review.
5 / 5
You're reviewing an endpoint that sends or receives large data objects. How do you open the discussion?
KEY PHRASE: "What's the expected payload size? We may need to consider chunking or compression if it's over a few MB" This opens the right design conversation by asking the right question and immediately following with the implications — chunking for streaming large responses, compression (gzip/brotli) to reduce transfer size, and a practical threshold (a few MB) to calibrate concern. Real examples: "Expected payload size? Over 1MB and we'll want gzip on the response"; "What's the payload size envelope — we may need streaming if it's unbounded"; "Payload over 5MB? Consider chunked transfer encoding or a signed S3 URL." Options B-D are too vague or don't lead to any design action.