pwp-api-design

API Design Skill

This skill defines standards for designing and reviewing APIs. Consistency and predictability are non-negotiable.

API Design Principles

1. Consistency over cleverness. Every endpoint follows the same patterns.
2. Predictability over flexibility. Predictable APIs are easier to consume, test, and debug.
3. 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