Learn API design patterns vocabulary: resource hierarchy, collection vs. singleton resources, sub-resources vs. query parameters, RPC-style endpoints, HATEOAS — for fluent API design discussions.
0 / 18 completed
1 / 18
The API designer says: 'We model this as a collection resource under /orders.' What is a 'collection resource' in REST?
A collection resource represents a set of items of the same type. For example, /orders is a collection resource. You can GET the whole collection, POST to add a new item, and access individual items via /orders/{id} (a singleton resource). The distinction matters for naming, HTTP method semantics, and pagination design.
2 / 18
A colleague says: 'Use sub-resources for things that only exist in the context of their parent.' Which URL pattern correctly uses a sub-resource?
/posts/123/comments is the correct sub-resource pattern. Comments in this design only exist in the context of post 123. Sub-resources express containment or strong ownership. Query parameters like ?postId=123 are more appropriate for optional filtering of independent resources.
3 / 18
The tech lead comments: 'This operation doesn't fit REST — consider an RPC-style endpoint.' When is an RPC-style endpoint appropriate?
RPC-style endpoints (e.g., POST /orders/123/cancel) are appropriate for actions or commands — like cancel, approve, send — that are not straightforward resource mutations. Forcing every action into REST resource semantics can produce awkward or misleading API designs. RPC-style is acceptable when the action doesn't map naturally to a resource lifecycle.
4 / 18
The architect mentions HATEOAS in the API design review. What does HATEOAS mean?
HATEOAS stands for Hypermedia As The Engine Of Application State. It is a REST constraint where API responses include links to related actions and resources, allowing clients to navigate the API dynamically without hardcoding URLs. For example, an order response might include links to 'cancel', 'ship', and 'invoice' actions based on the current state.
5 / 18
During a design review, the engineer asks: 'Should we use sub-resources or query parameters for filtering orders by status?' What is the recommended approach?
Query parameters are the standard approach for filtering a collection resource by attribute values. /orders?status=pending is idiomatic REST. Sub-resources express structural relationships (e.g., /orders/123/items), not attribute filtering. Using sub-resources for filter values (e.g., /orders/status/pending) conflates navigation with filtering.
6 / 18
PR Description
Subject: Implement new user profile endpoint
Body:
Hi team,
This PR introduces a new endpoint for retrieving and updating user profiles. We're using a nested resource structure to organize the data, with /users/{userId}/profile.
Reviewers, please focus on ensuring the response format adheres to the API contract defined in the Swagger spec. Let me know if you have any questions!
—John
This scenario presents a common situation during code reviews. The question tests understanding of when and why nested resource structures are used in API design. It's correct because nesting is often appropriate for data that logically belongs to a parent resource (the user) and has associated properties (the profile). Options A, C, and D misinterpret the purpose or RESTful principles involved; simply stating it's 'standard practice' doesn't explain *why* it's suitable here.
7 / 18
Reviewer: 'I'm a little concerned about this API design. We've created a resource hierarchy – a top-level `users` collection and then sub-resources for each user's profile. While it seems logical, is there a specific reason we aren't leveraging more explicit relationships within the API itself, perhaps through HATEOAS links? It feels like we're just nesting resources without explicitly stating how to navigate them.' Considering this feedback, which statement best captures the primary benefit of implementing a resource hierarchy, particularly when considering broader API discoverability and maintainability?
Consider that simply nesting resources doesn't inherently solve navigation problems. A well-designed API should guide clients towards related data.
The correct answer highlights that a resource hierarchy provides a clear and intuitive structure for clients. This reduces the complexity of URL manipulation required by the client-side code. The other options represent misconceptions: simply nesting resources doesn't *guarantee* discoverability, HATEOAS is an *additional* technique (and not always superior), and the reviewer's concern, while valid, isn't the core benefit being described here. A good API design should make navigation obvious, and a hierarchy facilitates this by grouping related data logically.
8 / 18
PR Description
Subject: Implement new user profile endpoint
Body:
Hi team,
This PR introduces a new endpoint for retrieving and updating user profiles. We're using a nested resource structure to organize the data, with /users/{userId}/profile.
Reviewers, please focus on ensuring the response format adheres to the API contract defined in the Swagger spec. Let me know if you have any questions!
—John
This scenario presents a common situation during code reviews. The question tests understanding of when and why nested resource structures are used in API design. It's correct because nesting is often appropriate for data that logically belongs to a parent resource (the user) and has associated properties (the profile). Options A, C, and D misinterpret the purpose or RESTful principles involved; simply stating it's 'standard practice' doesn't explain *why* it's suitable here.
9 / 18
Reviewer: 'I'm a little concerned about this API design. We've created a resource hierarchy – a top-level `users` collection and then sub-resources for each user's profile. While it seems logical, is there a specific reason we aren't leveraging more explicit relationships within the API itself, perhaps through HATEOAS links? It feels like we're just nesting resources without explicitly stating how to navigate them.' Considering this feedback, which statement best captures the primary benefit of implementing a resource hierarchy, particularly when considering broader API discoverability and maintainability?
Consider that simply nesting resources doesn't inherently solve navigation problems. A well-designed API should guide clients towards related data.
The correct answer highlights that a resource hierarchy provides a clear and intuitive structure for clients. This reduces the complexity of URL manipulation required by the client-side code. The other options represent misconceptions: simply nesting resources doesn't *guarantee* discoverability, HATEOAS is an *additional* technique (and not always superior), and the reviewer's concern, while valid, isn't the core benefit being described here. A good API design should make navigation obvious, and a hierarchy facilitates this by grouping related data logically.
10 / 18
PR Description
Subject: Implement new user profile endpoint
Body:
Hi team,
This PR introduces a new endpoint for retrieving and updating user profiles. We're using a nested resource structure to organize the data, with /users/{userId}/profile.
Reviewers, please focus on ensuring the response format adheres to the API contract defined in the Swagger spec. Let me know if you have any questions!
—John
This scenario presents a common situation during code reviews. The question tests understanding of when and why nested resource structures are used in API design. It's correct because nesting is often appropriate for data that logically belongs to a parent resource (the user) and has associated properties (the profile). Options A, C, and D misinterpret the purpose or RESTful principles involved; simply stating it's 'standard practice' doesn't explain *why* it's suitable here.
11 / 18
Reviewer: 'I'm a little concerned about this API design. We've created a resource hierarchy – a top-level `users` collection and then sub-resources for each user's profile. While it seems logical, is there a specific reason we aren't leveraging more explicit relationships within the API itself, perhaps through HATEOAS links? It feels like we're just nesting resources without explicitly stating how to navigate them.' Considering this feedback, which statement best captures the primary benefit of implementing a resource hierarchy, particularly when considering broader API discoverability and maintainability?
Consider that simply nesting resources doesn't inherently solve navigation problems. A well-designed API should guide clients towards related data.
The correct answer highlights that a resource hierarchy provides a clear and intuitive structure for clients. This reduces the complexity of URL manipulation required by the client-side code. The other options represent misconceptions: simply nesting resources doesn't *guarantee* discoverability, HATEOAS is an *additional* technique (and not always superior), and the reviewer's concern, while valid, isn't the core benefit being described here. A good API design should make navigation obvious, and a hierarchy facilitates this by grouping related data logically.
12 / 18
PR Description
Subject: Implement new user profile endpoint
Body:
Hi team,
This PR introduces a new endpoint for retrieving and updating user profiles. We're using a nested resource structure to organize the data, with /users/{userId}/profile.
Reviewers, please focus on ensuring the response format adheres to the API contract defined in the Swagger spec. Let me know if you have any questions!
—John
This scenario presents a common situation during code reviews. The question tests understanding of when and why nested resource structures are used in API design. It's correct because nesting is often appropriate for data that logically belongs to a parent resource (the user) and has associated properties (the profile). Options A, C, and D misinterpret the purpose or RESTful principles involved; simply stating it's 'standard practice' doesn't explain *why* it's suitable here.
13 / 18
Reviewer: 'I'm a little concerned about this API design. We've created a resource hierarchy – a top-level `users` collection and then sub-resources for each user's profile. While it seems logical, is there a specific reason we aren't leveraging more explicit relationships within the API itself, perhaps through HATEOAS links? It feels like we're just nesting resources without explicitly stating how to navigate them.' Considering this feedback, which statement best captures the primary benefit of implementing a resource hierarchy, particularly when considering broader API discoverability and maintainability?
Consider that simply nesting resources doesn't inherently solve navigation problems. A well-designed API should guide clients towards related data.
The correct answer highlights that a resource hierarchy provides a clear and intuitive structure for clients. This reduces the complexity of URL manipulation required by the client-side code. The other options represent misconceptions: simply nesting resources doesn't *guarantee* discoverability, HATEOAS is an *additional* technique (and not always superior), and the reviewer's concern, while valid, isn't the core benefit being described here. A good API design should make navigation obvious, and a hierarchy facilitates this by grouping related data logically.
14 / 18
Sarah (Backend Engineer): 'Okay team, we're using a resource hierarchy for user profiles – a top-level `/users` collection and then sub-resources like `/users/{userId}/profile'. Does that align with HATEOAS principles?',
HATEOAS (Hypermedia as the Engine of Application State) means that API endpoints should expose their relationships through hyperlinks. A nested resource structure like this *can* be part of a HATEOAS implementation if combined with links pointing to related resources. The core principle is discoverability, and this setup provides some of that.
15 / 18
Reviewer: 'I'm noticing we're using query parameters to filter orders by status. While functional, this might not be the most RESTful approach for complex filtering scenarios. What is a key benefit of utilizing sub-resources when dealing with filtering data like order statuses?',
RESTful API design favors using resources to represent entities. When filtering based on attributes like 'status', grouping related orders under a dedicated `/orders/{orderId}/status` sub-resource improves organization and allows for more complex filtering logic (e.g., multiple status filters) without cluttering the main `/orders` endpoint with numerous query parameters.
16 / 18
PR Description
Subject: Implement new user profile update endpoint
Body:
Hi team,
This PR introduces a new endpoint for updating user profiles. We've leveraged a resource hierarchy – a top-level `users` collection and sub-resources for individual profiles, allowing us to efficiently manage related data within the same URL structure. What is the primary advantage of this design choice in terms of API maintainability?
Using a resource hierarchy like this improves API maintainability because it reduces the number of URLs you need to track and understand. Changes to user profile data can be managed within the context of that specific `/users/{userId}/profile` sub-resource without impacting other parts of the API. This simplifies future development efforts.
17 / 18
David (Senior Developer): 'I'm working on designing the new customer order API. I'm considering whether to use sub-resources for individual orders or include all order details in a query parameter string. How does using sub-resources align with best practices for API design and discoverability?'
When designing an API, a well-structured hierarchy makes it easier for developers to understand how different entities relate to each other. Sub-resources like `/orders/{orderId}` clearly indicate that you're interacting with a specific order, improving discoverability and reducing the cognitive load on developers.
18 / 18
You're designing an API for managing products. You need to support filtering products by category and price range. Which approach is *most* aligned with RESTful principles regarding resource design?
RESTful APIs encourage a resource-oriented design. Separating filtering criteria into distinct sub-resources allows you to clearly define relationships between products and their attributes (category, price range). This improves API organization, maintainability, and makes it easier for developers to understand the structure of the product data.
What will I practice in "API Design Patterns Vocabulary"?
This is an API Design Language exercise set. It walks through 18 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 18 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.