Pwp api design

Skill shandar/pwp-plugin/skills/pwp-api-design

API design standards — consistent, predictable, documented endpoints. Use this skill whenever the user is building, reviewing, or planning an API. Also use when they mention REST endpoints, API routes, request/response shapes, status codes, pagination, versioning, or say things like 'design the API', 'what should this endpoint look like', 'review my API', or 'add an endpoint for X'. Covers REST conventions, status codes, response envelopes, pagination, filtering, versioning, and validation.From its SKILL.md

Install

npx -y skills add shandar/pwp-plugin --skill pwp-api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.3 KB, 709 tokens by cl100k_base, as published. Nobody here has run it

API 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

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.