Rest Best Practices
by @mike47512
Deep REST workflow—resource modeling, HTTP methods and safety, status codes, errors, pagination, caching, versioning, and idempotency. Use when designing HTT...
clawhub install rest-best-practices📖 About This Skill
name: rest-best-practices description: Deep REST workflow—resource modeling, HTTP methods and safety, status codes, errors, pagination, caching, versioning, and idempotency. Use when designing HTTP APIs or reviewing controllers and gateways.
REST Best Practices (Deep Workflow)
REST is HTTP semantics used consistently: resources as nouns, methods with meaning, predictable errors, and cacheable reads where safe.
When to Offer This Workflow
Trigger conditions:
Initial offer:
Use six stages: (1) resource model, (2) methods & safety, (3) status & errors, (4) pagination & filtering, (5) caching & conditional requests, (6) versioning & evolution). Confirm JSON conventions and authentication model.
Stage 1: Resource Model
Goal: Clear collection vs item resources; relationships via sub-paths or hypermedia links (HATEOAS optional).
Exit condition: Table or diagram of resources, identifiers, and canonical URLs.
Stage 2: Methods & Safety
Goal: GET/HEAD safe and idempotent; POST for creation or non-idempotent actions; PUT replaces; PATCH partial; DELETE removes.
Anti-patterns
Stage 3: Status & Errors
Goal: Correct 4xx vs 5xx; consistent error body (e.g., RFC 7807 Problem Details) with stable type codes and optional instance for support.
Stage 4: Pagination & Filtering
Goal: Cursor pagination for large lists; document sort/filter query params; cap page sizes.
Stage 5: Caching & Conditional Requests
Goal: ETag/Last-Modified for cacheable GET; Cache-Control directives; validate with intermediaries (CDN) when used.
Stage 6: Versioning & Evolution
Goal: URL prefix or header versioning; deprecation policy; Idempotency-Key on POST when clients retry.