home / skills / codingheader / myskills / 0xdarkmatter-rest-patterns

0xdarkmatter-rest-patterns skill

safe

/Skillstore/rest-patterns/0xdarkmatter-rest-patterns

This skill helps you design and audit RESTful APIs using standard HTTP methods, status codes, and patterns for caching and rate limiting.

This is most likely a fork of the rest-patterns skill from 0xdarkmatter

npx playbooks add skill codingheader/myskills --skill 0xdarkmatter-rest-patterns

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

Files (6)

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 helps backend engineers and API designers choose methods, status codes, endpoint layouts, and caching/rate-limiting strategies quickly. The content is focused on practical rules, anti-patterns, and short examples for common tasks.

How this skill works

The skill inspects common REST concerns: HTTP methods and their idempotency/cacheability, essential status codes and when to return them, resource and query parameter patterns, and security and rate-limiting checklists. It summarizes caching headers and client/server rate-limit signals and flags common API design mistakes. The goal is a quick decision aid you can consult while implementing or reviewing endpoints.

When to use it

Designing new REST endpoints and URL structures
Choosing HTTP methods and the correct status codes
Defining pagination, sorting, filtering, and sparse-field patterns
Implementing caching headers (Cache-Control, ETag) and CDN strategies
Setting up rate limiting and client throttling policies
Performing security and compliance checks for API surfaces

Best practices

Use nouns for resources and keep verbs out of URLs (e.g., /users not /getUsers)
Prefer GET for safe retrieval, POST for create, PUT for full replace, PATCH for partial updates, DELETE for removal
Always paginate collection responses and provide consistent links/metadata
Return appropriate HTTP status codes (201 for create with Location header, 204 for success with no body, 4xx for client errors)
Enforce HTTPS, validate inputs, and avoid sensitive data in URLs; combine auth (OAuth2/JWT) with rate limits
Expose caching semantics (Cache-Control, ETag) and use no-store for sensitive responses

Example use cases

Create a users collection with /users (GET list, POST create) and /users/{id} for single-resource ops
Implement cursor or page-based pagination: GET /orders?page=2&limit=20 and include total/next links
Add filtering and sorting to list endpoints: GET /products?category=tools&sort=price:asc
Protect APIs with per-client rate limits and respond with 429 + Retry-After header when exceeded
Use ETag and conditional GET to reduce bandwidth for frequently read resources

FAQ

When should I use PUT vs PATCH?

Use PUT to replace an entire resource when the client can send the full representation. Use PATCH for partial updates when you want to change only specific fields; document patch semantics clearly.

What status code for validation errors?

Use 422 Unprocessable Entity for semantic validation failures and 400 Bad Request for malformed syntax. Include machine-readable error details in the response body.