Comprehensive guide for designing RESTful APIs including resource modeling, versioning strategies, HATEOAS, pagination, filtering, and HTTP best practices

REST API Design Patterns A comprehensive skill for designing, implementing, and maintaining RESTful APIs. Master resource modeling, HTTP methods, versioning strategies, pagination, filtering, error handling, and best practices for building scalable, maintainable APIs using FastAPI, Express.js, and modern frameworks. When to Use This Skill Use this skill when: Designing a new RESTful API from scratch Building microservices with HTTP/REST interfaces Refactoring existing APIs for better design and consistency Implementing CRUD operations with proper HTTP semantics Adding versioning to an existing API Designing resource relationships and nested endpoints Implementing pagination, filtering, and sorting Handling errors and validation consistently Building hypermedia driven APIs (HATEOAS) Optimizing API performance with caching and compression Documenting APIs with OpenAPI/Swagger specifications Ensuring API security with authentication and authorization patterns Core REST Principles What is REST? REST (Representational State Transfer) is an architectural style for distributed systems that emphasizes: 1. Resource Based : Everything is a resource with a unique identifier (URI) 2. Standard Methods : Use standard HTTP methods (GET, POST, PUT, DELETE, PATCH) 3. Stateless : Each request contains all information needed to process it 4. Client Server : Clear separation between client and server 5. Cacheable : Responses can be cached for performance 6. Uniform Interface : Consistent patterns across the API REST Maturity Model (Richardson Maturity Model) Level 0 The Swamp of POX : Single URI, single HTTP method (usually POST) Example: /api with all operations in POST body Level 1 Resources : Multiple URIs, each representing a resource Example: /users , /posts , /products Level 2 HTTP Verbs : Proper use of HTTP methods Example: GET /users/123 , POST /users , PUT /users/123 Level 3 Hypermedia Controls (HATEOAS) : API responses include links to related resources Example: Response includes " links": {"self": "/users/123", "posts": "/users/123/posts"} Resource Modeling Resource Naming Conventions 1. Use Nouns, Not Verbs 2. Use Plural Nouns for Collections 3. Use Lowercase and Hyphens 4. Hierarchy for Related Resources Resource Design Patterns Pattern 1: Collection and Item Resources Pattern 2: Nested Resources (Parent Child Relationships) Pattern 3: Filtering Collections (Query Parameters) Pattern 4: Actions on Resources (Controllers) For operations that don't fit standard CRUD: Pattern 5: Bulk Operations HTTP Methods Deep Dive GET Retrieve Resources Characteristics: Safe: No side effects Idempotent: Multiple identical requests have the same effect Cacheable: Responses can be cached FastAPI Example: Express.js Example: POST Create Resources Characteristics: Not safe: Has side effects (creates resource) Not idempotent: Multiple requests create multiple resources Response should include Location header with new resource URI FastAPI Example: Express.js Example: PUT Replace Resource Characteristics: Not safe: Has side effects Idempotent: Multiple identical requests have the same effect Replaces entire resource (all fields required) FastAPI Example: Express.js Example: PATCH Partial Update Characteristics: Not safe: Has side effects Idempotent: Multiple identical requests have the same effect Updates only specified fields (partial update) FastAPI Example: Express.js Example: DELETE Remove Resource Characteristics: Not safe: Has side effects Idempotent: Multiple identical requests have the same effect Returns 204 No Content or 200 OK with response body FastAPI Example: Express.js Example: API Versioning Strategies Strategy 1: URI Versioning (Most Common) Version in the URI path clear, explicit, easy to understand. Pros: Explicit and visible Easy to route to different code versions Browser friendly Simple for documentation Cons: Creates multiple endpoints Can lead to code duplication URLs change between versions FastAPI Implementation: Express.js Implementation: Strategy 2: Header Versioning Version specified in custom header or Accept header. Pros: Clean URIs No URL pollution More "RESTful" (resources have single URI) Cons: Less visible Harder to test in browser More complex routing logic FastAPI Implementation: Express.js Implementation: Strategy 3: Content Negotiation (Accept Header) Version specified in Accept header with custom media types. FastAPI Implementation: Express.js Implementation: Strategy 4: Query Parameter Versioning Version as query parameter (least recommended). Cons: Mixes versioning with filtering Harder to cache Less clear separation of concerns Pagination Patterns Pattern 1: Offset Based Pagination (Traditional) Simple but can have performance issues with large datasets. FastAPI Implementation: Express.js Implementation: Pattern 2: Cursor Based Pagination (Recommended for Large Datasets) More efficient for large datasets, prevents issues with data changes during pagination. FastAPI Implementation: Express.js Implementation: Pattern 3: Page Based Pagination User friendly for UIs with page numbers. FastAPI Implementation: Express.js Implementation: Filtering and Sorting Advanced Filtering FastAPI Implementation: Express.js Implementation: Error Handling Best Practices Consistent Error Response Format Standard Error Response Structure: HTTP Status Codes Success Codes: 200 OK : Successful GET, PUT, PATCH, DELETE with response 201 Created : Successful POST creating a resource 202 Accepted : Request accepted for async processing 204 No Content : Successful DELETE with no response body Client Error Codes: 400 Bad Request : Invalid request syntax or validation error 401 Unauthorized : Authentication required 403 Forbidden : Authenticated but not authorized 404 Not Found : Resource doesn't exist 405 Method Not Allowed : HTTP method not supported 409 Conflict : Request conflicts with current state 422 Unprocessable Entity : Validation failed 429 Too Many Requests : Rate limit exceeded Server Error Codes: 500 Internal Server Error : Generic server error 502 Bad Gateway : Invalid response from upstream server 503 Service Unavailable : Server temporarily unavailable 504 Gateway Timeout : Upstream server timeout FastAPI Error Handling Express.js Error Handling HATEOAS and Hypermedia What is HATEOAS? HATEOAS (Hypermedia as the Engine of Application State) means including links to related resources in API responses. Benefits: Self documenting API Client doesn't need to construct URLs Easier API evolution Better discoverability FastAPI HATEOAS Implementation Express.js HATEOAS Implementation Performance Optimization Caching with ETags FastAPI Implementation: Express.js Implementation: Rate Limiting Express.js Implementation: Compression FastAPI Implementation: Express.js Implementation: Security Best Practices Authentication Patterns JWT Authentication in FastAPI: JWT Authentication in Express.js: Input Validation and Sanitization FastAPI Validation: API Documentation OpenAPI/Swagger with FastAPI FastAPI automatically generates OpenAPI documentation: Best Practices Summary API Design Principles 1. Use nouns for resources, not verbs 2. Use plural nouns for collections 3. Use HTTP methods correctly (GET, POST, PUT, PATCH, DELETE) 4. Use proper HTTP status codes 5. Version your API (URI versioning recommended) 6. Support pagination for collections 7. Allow filtering and sorting with query parameters 8. Return consistent error responses 9. Use HATEOAS for better discoverability 10. Document your API with OpenAPI/Swagger Security Principles 1. Always use HTTPS in production 2. Implement authentication (JWT, OAuth, API keys) 3. Validate all inputs thoroughly 4. Use rate limiting to prevent abuse 5. Sanitize outputs to prevent XSS 6. Implement CORS correctly 7. Use security headers (CSP, X Frame Options, etc.) 8. Log security events for monitoring 9. Keep dependencies updated 10. Never expose sensitive data in responses Performance Principles 1. Use caching (ETags, Cache Control headers) 2. Implement compression for large responses 3. Use pagination for large datasets 4. Optimize database queries (indexes, N+1 prevention) 5. Use async/await for I/O operations 6. Implement connection pooling 7. Monitor API performance (response times, error rates) 8. Use CDNs for static content 9. Implement proper logging without blocking 10. Load test your API regularly Skill Version : 1.0.0 Last Updated : October 2025 Skill Category : API Design, Backend Development, REST Architecture Compatible With : FastAPI, Express.js, Node.js, Python, HTTP Frameworks

rest-api-design-patterns