API Design Discussions: Phrases for Contract Negotiations
5 exercises on idempotency, versioning, contracts, and pagination language. Choose the most natural and professional option.
0 / 10 completed
1 / 10
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 / 10
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 / 10
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 / 10
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 / 10
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.
6 / 10
Reviewer: 'This endpoint returns a 201 status code on success. However, the documentation doesn't explicitly state whether it *always* creates a new resource or updates an existing one if the ID already exists. How should we address this ambiguity?'
Which response best reflects a constructive discussion during a code review?
This question tests understanding of documenting API behavior. Option A is passive and doesn't address the core ambiguity. Option B oversimplifies – a 201 doesn't *guarantee* creation. Option C proactively seeks clarification and proposes a more complete documentation strategy. Option D misinterprets the status code, ignoring the potential for confusion.
7 / 10
Slack Message: @johndoe is pushing a new version of the user service API. He's added a 'user_metadata' field to allow for storing custom data associated with each user. You want to ensure this change aligns with the broader API contract.
Which message would you send to him?
This focuses on API contract maintenance. Option A is too vague and doesn't focus on the formal agreement. Option B directly addresses the critical step of updating documentation, which is key to consistent API usage. Options C and D are reactive and neglect potential issues or the need for a more thorough discussion.
8 / 10
PR Description: The developer is adding an endpoint to retrieve product details by SKU. The API returns the product name, description, and price.
Which PR description best communicates this endpoint's functionality and potential limitations?
This checks for clear and informative PR descriptions. Option A is minimal and lacks context. Option B acknowledges the core functionality *and* highlights a potential limitation (lack of error handling), which is crucial. Options C and D introduce unsupported claims about performance or guarantees, which are not part of an API contract.
9 / 10
Standup Update: 'I'm working on implementing a new rate limiting strategy for the authentication service. We need to prevent abuse and ensure API stability.'
Which follow-up question demonstrates an understanding of contract negotiation regarding this change?
This tests understanding of potential impacts on consumers. Option A is simply gathering information. Option B directly addresses the contractual concern – how the change affects existing users and their access rights. Options C and D shift the focus to implementation details rather than the broader implications for the API contract.
10 / 10
API Response (Example): The system returns a JSON object with a `status` field ('success' or 'error') and a `data` field containing the requested resource.
You're discussing this response with another developer who is unfamiliar with API contracts. Which phrasing best clarifies the *guaranteed* behavior of the response?
This assesses understanding of API guarantees. Option A only describes the fields. Option B describes what happens on success. However, Option 3 explicitly states the *guarantee* – that 'success' means exactly that, and 'data' contains the expected resource. Option D is too permissive and doesn't define contract boundaries.
What will I practise in "API Design Discussions: Phrases for Contract Negotiations"?
This module focuses on Phrasebook — real workplace phrasing you'll use on the job. It contains 10 scenario-based multiple-choice questions with instant feedback.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to use with no account or sign-up required.
How many questions does this exercise have?
This module includes 10 questions. Each one gives an immediate right/wrong result plus a full explanation of the correct phrasing.
What happens if I answer a question incorrectly?
You'll see the correct answer highlighted straight away, along with a plain-English explanation of why it's right and why the other options don't fit — mistakes are part of the learning here.
Can I retry the exercise if I want a better score?
Yes — use the 'Try again' button on the results screen to reset your score and go through the questions again. There's no limit on attempts.
Who is this Phrasebook exercise for?
It's aimed at IT professionals with working English who want to sound more natural and precise around phrasebook — useful whether you're preparing for real conversations at work or just building confidence with the vocabulary.
Do I need an account to track my progress?
No account is needed. Your progress through the exercise is tracked locally in your browser for the current session, and you can replay the module at any time.
How is this different from reading a blog article?
This exercise is an interactive drill that tests and reinforces specific phrasing through multiple-choice questions with instant feedback, while blog articles explain concepts and vocabulary in prose. The two work well together.
Where can I find more Phrasebook exercises?
See the Phrasebook hub for more modules like this one, or browse the full Exercises page for other IT-English topics.
Can I complete this exercise on my phone?
Yes — every exercise on CoderSlingo is fully responsive and works on phones and tablets, so you can practise anywhere.