REST Design Vocabulary | API Design Language Exercises

1 / 5

An API design review includes the statement: "GET is both safe and idempotent. DELETE is idempotent but not safe. POST is neither safe nor idempotent."

A junior developer asks what "safe" means in REST terms. Which explanation is correct?

Option C is the RFC 7231 definition. Safety and idempotency are distinct HTTP semantics that determine how clients and intermediaries (browsers, caches, proxies) can behave:

Method	Safe	Idempotent	Browser can retry?
GET	✓ Yes	✓ Yes	Yes — safe to prefetch and cache
PUT	✗ No	✓ Yes	Yes — repeating the same PUT yields the same state
DELETE	✗ No	✓ Yes	Usually — deleting a deleted resource still leaves it deleted (404 is acceptable)
POST	✗ No	✗ No	No — browser warns before re-submitting a POST (e.g. form resubmission)
PATCH	✗ No	Not necessarily	Depends on implementation — PATCH to set a value is idempotent; PATCH to increment is not

Why this matters in practice: These properties determine whether retries are safe, whether caches can serve stale data, and how load balancers route requests. Using a GET to trigger mutations (e.g. GET /users/delete?id=5) is a security and correctness bug.

2 / 5

An API team is debating URI design. Which URI correctly follows REST resource naming best practices for a collection endpoint?

Option A follows the REST URI naming conventions established by Roy Fielding and widely adopted in API style guides (Google API Design Guide, Microsoft REST API Guidelines, Stripe, Twilio APIs).

Rule	Correct	Incorrect
Nouns, not verbs	/users, /orders, /payments	/getUsers, /createOrder, /deletePayment
Plural for collections	/users, /products	/user, /product
Lowercase, hyphen-separated	/shipping-addresses	/ShippingAddresses, /shipping_addresses
Hierarchy via path	/users/{id}/orders — orders belonging to a user	/getUserOrders?userId={id}

The HTTP method carries the verb: GET /users = list; POST /users = create; GET /users/{id} = fetch one; PUT /users/{id} = update; DELETE /users/{id} = delete. Encoding actions in the URL (/deleteUser) ignores HTTP method semantics and creates non-RESTful RPC-style endpoints.

3 / 5

An API requires every client request to include a Bearer authentication token in the Authorization header, even when the same client made an authenticated request moments earlier. The server never stores active sessions.

Which REST architectural constraint does this requirement implement?

Option D correctly identifies the stateless constraint, one of the six architectural constraints that define REST (from Roy Fielding's 2000 dissertation).

Constraint	Meaning
Client-Server	Separation of UI concerns (client) from data/logic concerns (server)
Stateless	Each request is complete — no server-side session state between calls
Cacheable	Responses must declare whether they are cacheable or not
Uniform interface	Consistent conventions for identifying resources and transferring representations
Layered system	Client cannot tell whether it communicates directly with the server or via an intermediary
Code on demand	Optional — server can send executable code (e.g. JavaScript) to clients

Practical consequence of statelessness: Any server in a load-balanced cluster can handle any request — no "sticky sessions" required. This is the fundamental enabler of horizontal scaling. The trade-off is that every request carries more data (the token/credentials), but the scalability benefits outweigh the overhead in most distributed systems.

4 / 5

A client sends an HTTP request with the header Accept: application/json. What does this header tell the server?

Option B correctly describes content negotiation, a fundamental HTTP mechanism defined in RFC 7231.

Header	Direction	Purpose
`Accept`	Client → Server	Preferred response media type(s)
`Accept-Language`	Client → Server	Preferred response language(s)
`Accept-Encoding`	Client → Server	Accepted compression formats (gzip, br)
`Content-Type`	Client → Server (request body)	Format of the request body being sent
`Content-Type`	Server → Client (response body)	Format of the response body being returned

Quality values (q-factors): Accept: application/json, text/html;q=0.9, */*;q=0.8 — the client prefers JSON (implicit q=1.0), then HTML, then anything. The server picks the highest-priority format it supports.

Status codes for content negotiation failures: 406 Not Acceptable — server cannot respond in any of the client's accepted media types. 415 Unsupported Media Type — server cannot process the request body's Content-Type.

5 / 5

When should a DELETE endpoint return 204 No Content rather than 200 OK with a response body?

Option A is the correct, nuanced answer. Neither 204 nor 200 is mandated by the REST spec — the choice is based on what information is useful to return.

Status code	When to use for DELETE	Example use case
204 No Content	Deletion succeeded; nothing useful to return	DELETE /tags/{id} — the tag is gone; no further info needed
200 OK + body	Deletion succeeded and there's useful info to return	DELETE /orders/{id} — return the cancelled order object for audit trail display
404 Not Found	Resource does not exist (some APIs prefer 204 here to preserve idempotency)	DELETE /users/99999 — user never existed
202 Accepted	Deletion is async — accepted but not yet complete	DELETE /large-datasets/{id} — queued for background processing

Design guidance: Be consistent within your API — if DELETE always returns 204, don't suddenly return 200 for some endpoints. Document the convention in your API design guide so consumers can write consistent error handling code.