REST Resource Design Patterns

Six foundational patterns for designing REST APIs. These patterns cover resource structure, filtering, pagination, and API evolution. Based on Roy Fielding's dissertation and industry practices at Stripe, GitHub, and Twilio.

Patterns

Resource Structure

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.

/users/users

Singleton Resource

A singleton resource identifies a single entity via its unique ID in the URL path. /users/123, /orders/ord_abc. GET reads it, PUT replaces it entirely, PATCH partially updates it, DELETE removes it. The ID in the URL is the permanent resource identifier.

/users/usr_123/users/usr_123

Sub-Resource (Nested Resource)

Sub-resources represent entities that only exist in the context of a parent resource. /users/123/orders, /posts/abc/comments. The nesting reflects a strong ownership relationship. Keep nesting to one or two levels maximum – deeper nesting creates brittle URLs and coupling.

/users/123/orders/posts/abc/comments

Query & Evolution

Filtering and Searching

Filtering narrows a collection response using query parameters. Search adds full-text or structured search. Use consistent query parameter naming across all endpoints: filter[field]=value or ?status=active&role=admin. Never use POST for reads, even for complex filters.

/users?status=active&role=admin/products?price_gte=10&price_lte=100

Pagination

Pagination limits collection responses to manageable chunks. Three strategies: offset/limit (simple, stale data risk), cursor-based (stable, scalable), page number (user-friendly). Cursor-based pagination is the modern standard for large, frequently updated collections. Always wrap results in an envelope with pagination metadata.

/users?page=2&per_page=20/users?offset=40&limit=20

API Versioning

API versioning lets you evolve an API without breaking existing clients. Three strategies: URL path prefix (/v1/), Accept header versioning, and query parameter versioning. URL prefix is the most widely adopted (Stripe, GitHub, Twilio all use it). Never make breaking changes to an existing version.

/api/v1/users/api/v2/users

Foundation: Roy Fielding's dissertation defines 6 REST constraints. These patterns apply the constraints in practice. Fielding dissertation Chapter 5 →