Course contentsShow
← Software Engineering
Lesson 777 of 1,93324. REST API DesignFree lesson

Singleton vs Collection Resources

Learn the difference between collection endpoints (/users) and individual resource endpoints (/users/123).

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 users
  • POST /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 123
  • PUT /users/123 — update user 123
  • DELETE /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.