Collection Resource
A collection resource represents a list of entities of the same type. It is identified by a plural noun URL (/users, /orders). GET returns the list with pagination. POST creates a new item. The collection URL is the canonical entry point for the resource type.
Details
Collection resources are the most common REST resource type. They group entities of the same kind under a single URL.
URL naming: plural nouns only. /users not /user. /products not /getProducts. The noun represents the collection.
HTTP methods on collections: GET /users – list items (with pagination, filtering, sorting) POST /users – create a new user, respond 201 Created with Location header DELETE /users – bulk delete (use with caution – require explicit confirmation)
Response shape for GET collection: Always return an object, never a bare array. Include pagination metadata alongside the data array. This lets you add total counts, cursors, and links without breaking changes.
Ordering: return items in a consistent, stable order. created_at DESC is the most common default. Make the sort field and direction configurable via query parameters.
URL Examples
| Pattern | Description |
|---|---|
| GET /users | List all users (paginated) |
| POST /users | Create a new user |
| GET /products | List all products |
| GET /orders?status=open | List open orders (filtered) |
Do
- +Use plural nouns: /users, /orders, /products
- +Return a wrapper object with data array and pagination metadata
- +Support cursor-based or offset pagination
- +Return 201 Created with Location header after POST
- +Default to a stable sort order (created_at DESC)
Don't
- !Never use verbs: /getUsers, /listOrders, /fetchProducts
- !Never return a bare JSON array – always wrap in an object
- !Never return all records without pagination for large collections
- !Never use singular nouns for collections: /user instead of /users
Examples
GET /api/v1/users?page=2&limit=20
{
"data": [
{ "id": "usr_1", "name": "Alice" },
{ "id": "usr_2", "name": "Bob" }
],
"pagination": {
"page": 2,
"limit": 20,
"total": 150,
"totalPages": 8
}
}POST /api/v1/users
Content-Type: application/json
{ "name": "Alice", "email": "[email protected]" }
---
HTTP/1.1 201 Created
Location: /api/v1/users/usr_123
{ "id": "usr_123", "name": "Alice", "email": "[email protected]" }