5 exercises on describing endpoints, request/response shapes, error cases and versioning notes in precise prose.
Key patterns
Name the method, path, request fields (with types), status code and response shape.
Document each error case: trigger, HTTP status, and a stable machine-readable code.
Versioning prose: introduced in, deprecated in, removed in, with a dated window.
State side effects and idempotency for any endpoint that mutates state.
0 / 5 completed
1 / 5
You are documenting an endpoint in prose for a spec. Which description of POST /v1/orders is the most precise and complete?
An endpoint description must pin down method, path, request shape, and success response.
Option B specifies:
the request body — exact field names and types (customerId: string, items as a non-empty array of { sku, quantity });
the success status — 201 Created;
the response shape — the created order with a server-generated id and an initial status.
The distractors lean on “order details”, “necessary information”, and “the usual order fields” — none of which tells a client developer what to send or expect. A good contract lets someone build the client without reading the server code. Always name fields, types, the status code, and whether IDs are client- or server-generated.
2 / 5
Which sentence documents an error case with enough precision for a client to handle it programmatically?
An error contract needs a trigger, a status code, and a machine-readable body.
Option C gives all three: the condition (items is empty), the HTTP status (422 Unprocessable Entity), and a stable error shape with a code clients can branch on (items_required) plus a human message.
“An error”, “a suitable error response”, and “as appropriate” are useless to an integrator — they can’t tell whether to retry, show a field error, or fail. Document a stable, enumerated error code (clients should switch on the code, never on the prose message), choose the right status (400 malformed vs 422 semantically invalid vs 409 conflict), and keep the body schema identical across all error responses.
3 / 5
How should a spec describe the response shape for GET /v1/users/{id} when the user does not exist?
Document both the present and the absent case explicitly.
Option B states the success path (200 OK with a named field list) and the not-found path (404 Not Found with a stable error code and no user body). Saying “and no user body” matters — it prevents a client from trying to read fields that aren’t there.
“Or nothing”, “if available”, and “handled elsewhere” leave the missing-resource behaviour undefined — does it return 200 with null, an empty object, or 404? Each forces different client code. For every read endpoint, specify the field set on success, the status and shape when the resource is missing, and which fields are nullable versus always present.
4 / 5
Your spec needs a versioning note for a field rename. Which prose is clearest about backwards compatibility?
A versioning note must say what changed, in which version, and what stays compatible.
Option C is unambiguous:
What — name → fullName;
Where — the change applies in v2, while v1 keeps returning name unchanged;
Deprecation window — name is deprecated with a concrete removal date.
The distractors don’t name a version, don’t promise compatibility, and use “might break” / “soon” instead of a date. Strong API prose uses precise verbs: introduced in, deprecated in, removed in, and continues to return…unchanged. Always give consumers a dated migration window rather than an open-ended “soon”.
5 / 5
Which description of an endpoint’s idempotency and side effects is precise enough to prevent double-charging?
For money-moving endpoints, the contract must state the idempotency mechanism exactly.
Option C names the side effect (charges the card), the idempotency mechanism (keyed on the Idempotency-Key header), the guaranteed behaviour on retry (returns the original result, no second charge), and the retention window (24 hours).
“Don’t call it twice”, “generally safe”, and “tries not to duplicate” are dangerously vague for payments — they don’t tell the client how to make a retry safe. Precise contract vocabulary: idempotent on key X, at-most-once, safe to retry, keys retained for N hours. Whenever an endpoint mutates state, document whether it is safe to retry and under what condition.