0xDarkMatter/rest-ops

REST Patterns

Quick reference for RESTful API design patterns and HTTP semantics.

HTTP Methods

| Method | Purpose | Idempotent | Cacheable | |--------|---------|------------|-----------| | GET | Retrieve resource(s) | Yes | Yes | | POST | Create new resource | No | No | | PUT | Replace entire resource | Yes | No | | PATCH | Partial update | Maybe | No | | DELETE | Remove resource | Yes | No |

Essential Status Codes

| Code | Name | Use | |------|------|-----| | 200 | OK | Success with body | | 201 | Created | POST success (add Location header) | | 204 | No Content | Success, no body | | 400 | Bad Request | Invalid syntax | | 401 | Unauthorized | Not authenticated | | 403 | Forbidden | Not authorized | | 404 | Not Found | Resource doesn't exist | | 422 | Unprocessable | Validation error | | 429 | Too Many Requests | Rate limited | | 500 | Server Error | Internal failure |

Resource Design

GET    /users              # List
POST   /users              # Create
GET    /users/{id}         # Get one
PUT    /users/{id}         # Replace
PATCH  /users/{id}         # Update
DELETE /users/{id}         # Delete

# Query parameters
GET /users?page=2&limit=20          # Pagination
GET /users?sort=created_at:desc     # Sorting
GET /users?role=admin               # Filtering

Security Checklist

• [ ] HTTPS/TLS only
• [ ] OAuth 2.0 or JWT for auth
• [ ] Validate all inputs
• [ ] Rate limit per client
• [ ] CORS headers configured
• [ ] No sensitive data in URLs
• [ ] Use no-store for sensitive responses

Common Mistakes

| Mistake | Fix | |---------|-----| | Verbs in URLs | /getUsers → /users | | Deep nesting | Flatten or use query params | | 200 for errors | Use proper 4xx/5xx | | No pagination | Always paginate collections | | Missing rate limits | Protect against abuse |

Quick Reference

| Task | Pattern | |------|---------| | Paginate | ?page=2&limit=20 | | Sort | ?sort=field:asc | | Filter | ?status=active | | Sparse fields | ?fields=id,name | | Include related | ?include=orders |

When to Use

• Designing new API endpoints
• Choosing HTTP methods and status codes
• Implementing caching headers
• Setting up rate limiting
• Structuring error responses

Additional Resources

For detailed patterns, load:

• ./references/status-codes.md - Complete status code reference with examples
• ./references/caching-patterns.md - Cache-Control, ETag, CDN patterns
• ./references/rate-limiting.md - Rate limiting strategies and headers
• ./references/response-formats.md - Errors, versioning, bulk ops, HATEOAS