REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.

API Design Patterns Conventions and best practices for designing consistent, developer friendly REST APIs. When to Activate Designing new API endpoints Reviewing existing API contracts Adding pagination, filtering, or sorting Implementing error handling for APIs Planning API versioning strategy Building public or partner facing APIs Resource Design URL Structure Naming Rules HTTP Methods and Status Codes Method Semantics Method Idempotent Safe Use For GET Yes Yes Retrieve resources POST No No Create resources, trigger actions PUT Yes No Full replacement of a resource PATCH No No Partial update of a resource DELETE Yes No Remove a resource PATCH can be made idempotent with proper implementation Status Code Reference Common Mistakes Response Format Success Response Collection Response (with Pagination) Error Response Response Envelope Variants Pagination Offset Based (Simple) Pros: Easy to implement, supports "jump to page N" Cons: Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts Cursor Based (Scalable) Pros: Consistent performance regardless of position, stable with concurrent inserts Cons: Cannot jump to arbitrary page, cursor is opaque When to Use Which Use Case Pagination Type Admin dashboards, small datasets (<10K) Offset Infinite scroll, feeds, large datasets Cursor Public APIs Cursor (default) with offset (optional) Search results Offset (users expect page numbers) Filtering, Sorting, and Search Filtering Sorting Full Text Search Sparse Fieldsets Authentication and Authorization Token Based Auth Authorization Patterns Rate Limiting Headers Rate Limit Tiers Tier Limit Window Use Case Anonymous 30/min Per IP Public endpoints Authenticated 100/min Per user Standard API access Premium 1000/min Per API key Paid API plans Internal 10000/min Per service Service to service Versioning URL Path Versioning (Recommended) Pros: Explicit, easy to route, cacheable Cons: URL changes between versions Header Versioning Pros: Clean URLs Cons: Harder to test, easy to forget Versioning Strategy Implementation Patterns TypeScript (Next.js API Route) Python (Django REST Framework) Go (net/http) API Design Checklist Before shipping a new endpoint: [ ] Resource URL follows naming conventions (plural, kebab case, no verbs) [ ] Correct HTTP method used (GET for reads, POST for creates, etc.) [ ] Appropriate status codes returned (not 200 for everything) [ ] Input validated with schema (Zod, Pydantic, Bean Validation) [ ] Error responses follow standard format with codes and messages [ ] Pagination implemented for list endpoints (cursor or offset) [ ] Authentication required (or explicitly marked as public) [ ] Authorization checked (user can only access their own resources) [ ] Rate limiting configured [ ] Response does not leak internal details (stack traces, SQL errors) [ ] Consistent naming with existing endpoints (camelCase vs snake case) [ ] Documented (OpenAPI/Swagger spec updated)

api-design