rest-patterns_skill

Overview

This skill is a compact reference for RESTful API design patterns, HTTP semantics, caching, and rate limiting. It summarizes HTTP methods, essential status codes, resource and endpoint patterns, security checkpoints, and common mistakes. Use it as a quick decision aid when designing or reviewing APIs.

How this skill works

The skill inspects common REST concerns and provides concise, actionable guidance: which HTTP methods to use, recommended status codes, resource URL patterns, query parameter conventions, and cache/rate-limit headers. It flags security items (TLS, auth, input validation) and lists common anti-patterns and fixes. Links point to deeper references for status codes, caching, rate limiting, and response formats.

When to use it

• Designing new REST endpoints or resources
• Choosing HTTP methods and appropriate status codes
• Defining pagination, sorting, filtering, and sparse-field patterns
• Implementing caching headers, ETag/Cache-Control, or CDN rules
• Planning rate limiting strategies and headers
• Reviewing API security and common anti-patterns

Best practices

• Prefer semantic methods: GET for reads, POST for create, PUT/PATCH for updates, DELETE for removal
• Return correct status codes (201 for create, 204 for no content, 4xx for client errors)
• Keep resource URLs noun-based and shallow; avoid verbs and deep nesting
• Always paginate collections and offer sorting/filtering query params
• Enforce HTTPS, authenticate with OAuth2/JWT, validate inputs, and avoid sensitive data in URLs
• Define rate limits per client and expose standard headers (Retry-After, X-RateLimit-*)

Example use cases

• Designing a /users resource with list, create, get, update, delete endpoints
• Choosing between PUT and PATCH when implementing updates to user profiles
• Configuring Cache-Control and ETag for GET endpoints behind a CDN
• Setting rate limits for public API keys and returning 429 with Retry-After
• Standardizing pagination and sparse-field queries across multiple endpoints