🌐 REST Design Vocabulary
Master core REST terminology: safe vs. idempotent methods, resource naming, statelessness, content negotiation, and status code semantics. Intermediate
0 / 25 completed
1 / 25
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 / 25
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 / 25
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 / 25
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 / 25
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.
6 / 25
Senior Developer: 'Okay team, I'm reviewing this PR for the new user profile API. I noticed you're using a `POST /users` endpoint to create profiles. While technically functional, it violates REST principles. Specifically, creating a resource typically requires a GET request to retrieve its ID *before* attempting to modify it. Can you explain why you chose POST here and what alternatives we could have considered?', (This excerpt is from a code review comment)This question assesses understanding of a core REST design principle: the distinction between retrieval and modification. While
POST /users *can* be used, it's generally discouraged for creating resources as it doesn't follow the standard pattern of getting an ID first. The correct answer highlights that retrieving the ID before modifying aligns with idempotency and promotes a cleaner API design. Option A is incorrect because efficiency isn't the primary driver of RESTful design choices; option D misattributes responsibility, and option B is technically true but misses the fundamental principle being discussed.7 / 25
During a Slack discussion about the design of our new `products` API, a developer proposes using a `POST /products/new` endpoint to create new product listings. Another team member responds: 'I'm not sure that aligns with RESTful principles. Shouldn't we be using a `GET /products/{id}` to retrieve the ID *before* attempting to update or create?' Which of the following best explains why the second developer's concern is valid?
The core principle behind RESTful API design is minimizing round trips between the client and server. Using a `GET` request to obtain an ID before creating a resource forces the server to perform one additional request, whereas a `POST` directly creates the resource. While performance *can* be a factor in some designs, adhering to REST principles of idempotency and safe operations is generally more important for long-term maintainability and scalability. Option A is incorrect as PUT/POST typically create resources; option C is a common misconception regarding caching but doesn't address the fundamental design issue; and option D suggests an overcomplicated solution.
8 / 25
Reviewing a draft API design for an e-commerce platform, a developer asks: 'I'm using a `PUT /orders/{id}` endpoint to update existing orders. Is that the correct way to modify order data according to REST principles?' A senior engineer responds: 'Not necessarily. While
PUT is generally appropriate for updating entire resources, using it for specific fields within an order might lead to inconsistencies if the server doesn't handle partial updates correctly.' Which of the following statements best describes why this concern is valid?The core issue here isn't about
PUT being inherently wrong; it's about the server's implementation. PUT requires replacing the *entire* resource with the new version, while a server might not be designed to handle partial updates via a PUT request. Using PATCH is more suitable for modifying specific fields without requiring a full replacement, ensuring data consistency.9 / 25
A developer is designing a REST API for a library system. They want to allow users to reserve books. The current design proposes using a `POST /reservations` endpoint to create reservations, accepting details like the book ID and user ID as parameters in the request body. Another team member raises concerns about this approach. Which of the following best explains why this design choice might be problematic from a RESTful perspective?
The core issue here is the representation of resources. REST advocates representing entities as distinct resources with unique identifiers. Treating the 'reservation' solely as an action (a POST operation) obscures its identity and makes it harder to manage and track over time. While a POST could be used, it's better practice to create a resource for the reservation itself, aligning with the principles of RESTful design by clearly defining what is being manipulated.
10 / 25
Liam: "Hey team, I'm building out the new reporting API. I've created a `GET /reports/{reportId}` endpoint to retrieve individual reports based on their ID. Should I be using POST instead?"The core concept here is understanding that GET requests in REST *are* safe and idempotent. This means they should never modify a resource and can be repeated multiple times without changing the result. While retrieving sensitive data *requires* careful consideration of security (option A), the fundamental design choice of using GET for retrieval is correct according to REST principles. Option B incorrectly states that POST is always preferred for retrieval; it's crucial to apply the rules of REST, not just implement a different approach.
11 / 25
Senior Developer: 'Okay team, I'm reviewing this PR for the new user profile API. I noticed you're using a `POST /users` endpoint to create profiles. While technically functional, it violates REST principles. Specifically, creating a resource typically requires a GET request to retrieve its ID *before* attempting to modify it. Can you explain why you chose POST here and what alternatives we could have considered?', (This excerpt is from a code review comment)This question assesses understanding of a core REST design principle: the distinction between retrieval and modification. While
POST /users *can* be used, it's generally discouraged for creating resources as it doesn't follow the standard pattern of getting an ID first. The correct answer highlights that retrieving the ID before modifying aligns with idempotency and promotes a cleaner API design. Option A is incorrect because efficiency isn't the primary driver of RESTful design choices; option D misattributes responsibility, and option B is technically true but misses the fundamental principle being discussed.12 / 25
During a Slack discussion about the design of our new `products` API, a developer proposes using a `POST /products/new` endpoint to create new product listings. Another team member responds: 'I'm not sure that aligns with RESTful principles. Shouldn't we be using a `GET /products/{id}` to retrieve the ID *before* attempting to update or create?' Which of the following best explains why the second developer's concern is valid?
The core principle behind RESTful API design is minimizing round trips between the client and server. Using a `GET` request to obtain an ID before creating a resource forces the server to perform one additional request, whereas a `POST` directly creates the resource. While performance *can* be a factor in some designs, adhering to REST principles of idempotency and safe operations is generally more important for long-term maintainability and scalability. Option A is incorrect as PUT/POST typically create resources; option C is a common misconception regarding caching but doesn't address the fundamental design issue; and option D suggests an overcomplicated solution.
13 / 25
Reviewing a draft API design for an e-commerce platform, a developer asks: 'I'm using a `PUT /orders/{id}` endpoint to update existing orders. Is that the correct way to modify order data according to REST principles?' A senior engineer responds: 'Not necessarily. While
PUT is generally appropriate for updating entire resources, using it for specific fields within an order might lead to inconsistencies if the server doesn't handle partial updates correctly.' Which of the following statements best describes why this concern is valid?The core issue here isn't about
PUT being inherently wrong; it's about the server's implementation. PUT requires replacing the *entire* resource with the new version, while a server might not be designed to handle partial updates via a PUT request. Using PATCH is more suitable for modifying specific fields without requiring a full replacement, ensuring data consistency.14 / 25
A developer is designing a REST API for a library system. They want to allow users to reserve books. The current design proposes using a `POST /reservations` endpoint to create reservations, accepting details like the book ID and user ID as parameters in the request body. Another team member raises concerns about this approach. Which of the following best explains why this design choice might be problematic from a RESTful perspective?
The core issue here is the representation of resources. REST advocates representing entities as distinct resources with unique identifiers. Treating the 'reservation' solely as an action (a POST operation) obscures its identity and makes it harder to manage and track over time. While a POST could be used, it's better practice to create a resource for the reservation itself, aligning with the principles of RESTful design by clearly defining what is being manipulated.
15 / 25
Liam: "Hey team, I'm building out the new reporting API. I've created a `GET /reports/{reportId}` endpoint to retrieve individual reports based on their ID. Should I be using POST instead?"The core concept here is understanding that GET requests in REST *are* safe and idempotent. This means they should never modify a resource and can be repeated multiple times without changing the result. While retrieving sensitive data *requires* careful consideration of security (option A), the fundamental design choice of using GET for retrieval is correct according to REST principles. Option B incorrectly states that POST is always preferred for retrieval; it's crucial to apply the rules of REST, not just implement a different approach.
16 / 25
Senior Developer: 'Okay team, I'm reviewing this PR for the new user profile API. I noticed you're using a `POST /users` endpoint to create profiles. While technically functional, it violates REST principles. Specifically, creating a resource typically requires a GET request to retrieve its ID *before* attempting to modify it. Can you explain why you chose POST here and what alternatives we could have considered?', (This excerpt is from a code review comment)This question assesses understanding of a core REST design principle: the distinction between retrieval and modification. While
POST /users *can* be used, it's generally discouraged for creating resources as it doesn't follow the standard pattern of getting an ID first. The correct answer highlights that retrieving the ID before modifying aligns with idempotency and promotes a cleaner API design. Option A is incorrect because efficiency isn't the primary driver of RESTful design choices; option D misattributes responsibility, and option B is technically true but misses the fundamental principle being discussed.17 / 25
During a Slack discussion about the design of our new `products` API, a developer proposes using a `POST /products/new` endpoint to create new product listings. Another team member responds: 'I'm not sure that aligns with RESTful principles. Shouldn't we be using a `GET /products/{id}` to retrieve the ID *before* attempting to update or create?' Which of the following best explains why the second developer's concern is valid?
The core principle behind RESTful API design is minimizing round trips between the client and server. Using a `GET` request to obtain an ID before creating a resource forces the server to perform one additional request, whereas a `POST` directly creates the resource. While performance *can* be a factor in some designs, adhering to REST principles of idempotency and safe operations is generally more important for long-term maintainability and scalability. Option A is incorrect as PUT/POST typically create resources; option C is a common misconception regarding caching but doesn't address the fundamental design issue; and option D suggests an overcomplicated solution.
18 / 25
Reviewing a draft API design for an e-commerce platform, a developer asks: 'I'm using a `PUT /orders/{id}` endpoint to update existing orders. Is that the correct way to modify order data according to REST principles?' A senior engineer responds: 'Not necessarily. While
PUT is generally appropriate for updating entire resources, using it for specific fields within an order might lead to inconsistencies if the server doesn't handle partial updates correctly.' Which of the following statements best describes why this concern is valid?The core issue here isn't about
PUT being inherently wrong; it's about the server's implementation. PUT requires replacing the *entire* resource with the new version, while a server might not be designed to handle partial updates via a PUT request. Using PATCH is more suitable for modifying specific fields without requiring a full replacement, ensuring data consistency.19 / 25
A developer is designing a REST API for a library system. They want to allow users to reserve books. The current design proposes using a `POST /reservations` endpoint to create reservations, accepting details like the book ID and user ID as parameters in the request body. Another team member raises concerns about this approach. Which of the following best explains why this design choice might be problematic from a RESTful perspective?
The core issue here is the representation of resources. REST advocates representing entities as distinct resources with unique identifiers. Treating the 'reservation' solely as an action (a POST operation) obscures its identity and makes it harder to manage and track over time. While a POST could be used, it's better practice to create a resource for the reservation itself, aligning with the principles of RESTful design by clearly defining what is being manipulated.
20 / 25
Liam: "Hey team, I'm building out the new reporting API. I've created a `GET /reports/{reportId}` endpoint to retrieve individual reports based on their ID. Should I be using POST instead?"The core concept here is understanding that GET requests in REST *are* safe and idempotent. This means they should never modify a resource and can be repeated multiple times without changing the result. While retrieving sensitive data *requires* careful consideration of security (option A), the fundamental design choice of using GET for retrieval is correct according to REST principles. Option B incorrectly states that POST is always preferred for retrieval; it's crucial to apply the rules of REST, not just implement a different approach.
21 / 25
Senior Developer: 'Okay team, I'm reviewing this PR for the new user profile API. I noticed you're using a `POST /users` endpoint to create profiles. While technically functional, it violates REST principles. Specifically, creating a resource typically requires a GET request to retrieve its ID *before* attempting to modify it. Can you explain why you chose POST here and what alternatives we could have considered?', (This excerpt is from a code review comment)This question assesses understanding of a core REST design principle: the distinction between retrieval and modification. While
POST /users *can* be used, it's generally discouraged for creating resources as it doesn't follow the standard pattern of getting an ID first. The correct answer highlights that retrieving the ID before modifying aligns with idempotency and promotes a cleaner API design. Option A is incorrect because efficiency isn't the primary driver of RESTful design choices; option D misattributes responsibility, and option B is technically true but misses the fundamental principle being discussed.22 / 25
During a Slack discussion about the design of our new `products` API, a developer proposes using a `POST /products/new` endpoint to create new product listings. Another team member responds: 'I'm not sure that aligns with RESTful principles. Shouldn't we be using a `GET /products/{id}` to retrieve the ID *before* attempting to update or create?' Which of the following best explains why the second developer's concern is valid?
The core principle behind RESTful API design is minimizing round trips between the client and server. Using a `GET` request to obtain an ID before creating a resource forces the server to perform one additional request, whereas a `POST` directly creates the resource. While performance *can* be a factor in some designs, adhering to REST principles of idempotency and safe operations is generally more important for long-term maintainability and scalability. Option A is incorrect as PUT/POST typically create resources; option C is a common misconception regarding caching but doesn't address the fundamental design issue; and option D suggests an overcomplicated solution.
23 / 25
Reviewing a draft API design for an e-commerce platform, a developer asks: 'I'm using a `PUT /orders/{id}` endpoint to update existing orders. Is that the correct way to modify order data according to REST principles?' A senior engineer responds: 'Not necessarily. While
PUT is generally appropriate for updating entire resources, using it for specific fields within an order might lead to inconsistencies if the server doesn't handle partial updates correctly.' Which of the following statements best describes why this concern is valid?The core issue here isn't about
PUT being inherently wrong; it's about the server's implementation. PUT requires replacing the *entire* resource with the new version, while a server might not be designed to handle partial updates via a PUT request. Using PATCH is more suitable for modifying specific fields without requiring a full replacement, ensuring data consistency.24 / 25
A developer is designing a REST API for a library system. They want to allow users to reserve books. The current design proposes using a `POST /reservations` endpoint to create reservations, accepting details like the book ID and user ID as parameters in the request body. Another team member raises concerns about this approach. Which of the following best explains why this design choice might be problematic from a RESTful perspective?
The core issue here is the representation of resources. REST advocates representing entities as distinct resources with unique identifiers. Treating the 'reservation' solely as an action (a POST operation) obscures its identity and makes it harder to manage and track over time. While a POST could be used, it's better practice to create a resource for the reservation itself, aligning with the principles of RESTful design by clearly defining what is being manipulated.
25 / 25
Liam: "Hey team, I'm building out the new reporting API. I've created a `GET /reports/{reportId}` endpoint to retrieve individual reports based on their ID. Should I be using POST instead?"The core concept here is understanding that GET requests in REST *are* safe and idempotent. This means they should never modify a resource and can be repeated multiple times without changing the result. While retrieving sensitive data *requires* careful consideration of security (option A), the fundamental design choice of using GET for retrieval is correct according to REST principles. Option B incorrectly states that POST is always preferred for retrieval; it's crucial to apply the rules of REST, not just implement a different approach.
Frequently Asked Questions
What will I practice in "REST Design Vocabulary | API Design Language Exercises"?
This is an API Design Language exercise set. It walks through 25 scenario-based multiple-choice questions built around real usage of API Design Language terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 25 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the API Design Language vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more API Design Language exercises?
See the API Design Language exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — API Design Language vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.