What status code signals a successful creation?

201 Created, with a Location header pointing to the new resource.

How should rate limiting be communicated to clients?

Return 429 Too Many Requests and document rate limits per client.

Which headers are important for caching REST responses?

Cache-Control and ETag, plus secure use of no-store where needed.

rest-patterns

npx machina-cli add skill aiskillstore/marketplace/rest-patterns --openclaw

Files (1)

SKILL.md

2.9 KB

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

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

Source

git clone https://github.com/aiskillstore/marketplace/blob/main/skills/0xdarkmatter/rest-patterns/SKILL.mdView on GitHub

Overview

Quick reference for RESTful API design patterns, HTTP semantics, caching, and rate limiting. It helps teams select appropriate methods, status codes, and query patterns to build scalable, predictable APIs.

How This Skill Works

HTTP methods map to resource operations (GET for read, POST for create, PUT/PATCH for updates, DELETE for removal). The guide enumerates status codes, and shows common query params for pagination, sorting, and filtering, plus security considerations and common mistakes to avoid in REST design.

When to Use It

Designing new API endpoints with RESTful conventions.
Choosing HTTP methods and status codes for resources.
Implementing caching headers and cache validation strategies.
Setting up rate limiting to protect APIs from abuse.
Structuring endpoints with pagination, sorting, and filtering.

Quick Start

Step 1: Define resource endpoints and map HTTP methods (GET, POST, PUT, PATCH, DELETE).
Step 2: Specify status codes, pagination, sorting, and filtering patterns (e.g., ?page=2&limit=20, ?sort=created_at:desc).
Step 3: Implement caching and rate limiting, validate inputs, and secure transport.

Best Practices

Use proper HTTP verbs (GET, POST, PUT, PATCH, DELETE) and ensure idempotence where applicable.
Return appropriate status codes (200/201/204/4xx/5xx) and avoid 200s for errors.
Paginate collections and support ?page, ?limit, ?sort, and ?filter query params.
Apply rate limiting per client and respond with 429 when limits are exceeded.
Use caching headers (Cache-Control, ETag) and secure transport (HTTPS).

Example Use Cases

GET /users to list users with ?page and ?limit
POST /users to create a user (with Location header pointing to /users/{id})
GET /users/{id} to fetch a single user
PUT /users/{id} to replace a user resource
PATCH /users/{id} to partially update a user

Frequently Asked Questions

Add this skill to your agents