home / skills / 0xdarkmatter / claude-mods / rest-patterns

rest-patterns skill

safe

/skills/rest-patterns

This skill provides quick RESTful API design guidance, covering methods, status codes, caching, and rate limiting to improve consistency and reliability.

npx playbooks add skill 0xdarkmatter/claude-mods --skill rest-patterns

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

2.9 KB

---
name: rest-patterns
description: "Quick reference for RESTful API design patterns, HTTP semantics, caching, and rate limiting. Triggers on: rest api, http methods, status codes, api design, endpoint design, api versioning, rate limiting, caching headers."
allowed-tools: "Read Write"
---

# 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

```http
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

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

FAQ

When should I use PUT vs PATCH?

Use PUT to replace an entire resource; use PATCH for partial updates. If partial updates are common and well-defined, implement PATCH. Ensure idempotency expectations are documented.

What status code for validation errors?

Return 422 Unprocessable Entity for semantic validation errors on well-formed requests. Use 400 for malformed syntax and 4xx codes for other client errors.