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 / 5 completed
1 / 5
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 / 5
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 / 5
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 / 5
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 / 5
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.