Singleton vs Collection Resources
You'll learn how to distinguish between endpoints that represent a single resource and those that represent a collection of resources in REST API design.
The Core Distinction
In REST APIs, you work with two fundamental types of endpoints:
- Collection resources represent a group of items (like
/users,/products,/orders) - Singleton resources represent a single, specific item (like
/users/123,/products/456,/orders/789)
Think of it like a library: the entire shelving system is your collection, while a single book you've pulled off the shelf is your singleton.
Collection Resources
Collection endpoints operate on the entire group:
GET /users— retrieve a list of all usersPOST /users— create a new user in the collection
The path is typically a plural noun. These endpoints often support filtering, pagination, and sorting to manage potentially large result sets.
Singleton Resources
Singleton endpoints target one specific resource, identified by its unique identifier:
GET /users/123— retrieve user with ID 123PUT /users/123— update user 123DELETE /users/123— remove user 123
The path includes the resource identifier appended to the collection path. You're no longer working with the group—you're working with one member of that group.
Hierarchical Resources
This pattern extends to nested relationships:
/users/123/orders— collection of orders for user 123/users/123/orders/789— a specific order for that user
Each level alternates between collection (plural) and singleton (identifier).
Key Takeaway: Collection resources (/users) represent groups and support listing and creation, while singleton resources (/users/123) represent individual items and support retrieval, updates, and deletion. The URL path structure reflects this hierarchy clearly.