pwp-api-design
Scannednpx machina-cli add skill shandar/pwp-plugin/pwp-api-design --openclawAPI Design Skill
This skill defines standards for designing and reviewing APIs. Consistency and predictability are non-negotiable.
API Design Principles
- Consistency over cleverness. Every endpoint follows the same patterns.
- Predictability over flexibility. Predictable APIs are easier to consume, test, and debug.
- Explicit over implicit. Errors should be clear. Status codes should be correct.
REST API Conventions
URL Structure
GET /api/v1/{resources} → List
GET /api/v1/{resources}/{id} → Get one
POST /api/v1/{resources} → Create
PUT /api/v1/{resources}/{id} → Replace
PATCH /api/v1/{resources}/{id} → Partial update
DELETE /api/v1/{resources}/{id} → Delete
Rules: plural nouns, no verbs in URLs, max 2 levels of nesting, query params for filtering/sorting/pagination.
HTTP Status Codes
| Code | Meaning | When to Use |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid input |
| 401 | Unauthorized | Missing/invalid auth |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Duplicate/state conflict |
| 422 | Unprocessable | Semantic errors |
| 429 | Too Many Requests | Rate limited |
| 500 | Server Error | Unhandled exception |
Response Envelope
// Success
{ "data": { ... }, "meta": { "page": 1, "per_page": 20, "total": 142 } }
// Error
{ "error": { "code": "VALIDATION_ERROR", "message": "Email is required", "details": [...] } }
Pagination
Offset-based: ?page=2&per_page=20
Cursor-based (large datasets): ?cursor=abc123&limit=20
Filtering & Sorting
?category=electronics&min_price=100&sort=-created_at
Versioning
- Version in URL path:
/api/v1/... - Old versions supported 6+ months after deprecation
Input Validation
- Validate at the boundary
- Return specific errors with field-level details
- Reject or ignore unknown fields
Review Checklist
- URLs use plural nouns, no verbs
- HTTP status codes are correct
- Response shape is consistent
- Error responses include code, message, details
- Input validation at boundary
- Pagination on list endpoints
- Auth on protected endpoints
- Rate limiting configured
- API documented (OpenAPI or equivalent)
Anti-Patterns
| Anti-Pattern | Do This Instead |
|---|---|
| Verbs in URLs | Use HTTP methods |
| 200 for everything | Correct status codes |
| Leaking internal errors | Safe, structured responses |
| No pagination | Always paginate lists |
| Breaking changes without versioning | Version and deprecate gracefully |
Source
git clone https://github.com/shandar/pwp-plugin/blob/main/skills/pwp-api-design/SKILL.mdView on GitHub Overview
Defines standards for designing and reviewing APIs, prioritizing consistency and predictability. It covers REST conventions, status codes, response envelopes, pagination, filtering, versioning, and validation to reduce surprises for clients.
How This Skill Works
Apply the REST conventions: URL structure stays /api/v1/{resources} with plural nouns, no verbs, and a max of two nesting levels; map HTTP methods to CRUD operations. Use standard HTTP status codes and a consistent envelope for both success and error responses, with field-level validation details. Version APIs in the URL and validate inputs at the boundary.
When to Use It
- Designing a new REST API from scratch
- Reviewing an existing API for consistency and predictability
- Planning API versioning or deprecation strategy
- Adding pagination, filtering, or sorting to list endpoints
- Defining clear error handling and structured error responses
Quick Start
- Step 1: Align endpoints to /api/v1/{resources} using plural nouns and avoid verbs
- Step 2: Use proper HTTP methods and status codes, and return a consistent envelope for both success and error cases
- Step 3: Add pagination, filtering, and versioning in the URL; document the API (OpenAPI) and enforce boundary validation
Best Practices
- Use plural nouns and avoid verbs in URLs; restrict nesting to two levels
- Return appropriate HTTP status codes for each operation (e.g., 200/201/204/400/401/403/404/409/422/429/500)
- Envelope responses consistently: success uses a data object; errors use a structured error object
- Always paginate list endpoints and support filtering/sorting via query params
- Document the API (e.g., OpenAPI) and validate inputs at the boundary with detailed field errors
Example Use Cases
- List products: GET /api/v1/products?page=1&per_page=20
- Get a product: GET /api/v1/products/{id}
- Create a product: POST /api/v1/products with a JSON body containing name and price
- Partial update: PATCH /api/v1/products/{id} with fields to change
- Validation error example: a structured error response with a code like VALIDATION_ERROR and field-level details
