API Design Skill — Professional API Patterns
This skill provides comprehensive API design guidance following industry best practices.
RESTful API Standards
URL Structure
GET /api/v1/resources # List (paginated, filtered) GET /api/v1/resources/:id # Detail (with includes) POST /api/v1/resources # Create PATCH /api/v1/resources/:id # Partial update PUT /api/v1/resources/:id # Full replace DELETE /api/v1/resources/:id # Delete (soft by default) POST /api/v1/resources/:id/restore # Restore soft-deleted
Response Envelope
typescript// Success - Single { data: { ... }, meta: { requestId, timestamp } } // Success - Collection { data: [...], meta: { requestId, timestamp }, pagination: { page: 1, perPage: 20, total: 150, totalPages: 8, hasNext: true, hasPrev: false } } // Error { error: { code: "VALIDATION_ERROR", message: "Human-readable message", details: [ { field: "email", message: "Invalid email format" } ] }, meta: { requestId, timestamp } }
Filtering & Sorting
GET /api/v1/products? filter[category]=electronics& filter[price_min]=10& filter[price_max]=100& filter[status]=active& sort=-createdAt,name& page=2& perPage=50& include=category,variants
HTTP Status Codes
| Code | Usage |
|---|---|
| 200 | Success (GET, PATCH, PUT, DELETE) |
| 201 | Created (POST) |
| 204 | No Content (successful DELETE with no body) |
| 400 | Validation Error |
| 401 | Unauthorized (missing/invalid auth) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not Found |
| 409 | Conflict (duplicate, version mismatch) |
| 422 | Unprocessable Entity (business rule violation) |
| 429 | Too Many Requests (rate limiting) |
| 500 | Internal Server Error |
Versioning Strategy
URL Versioning (recommended for REST): /api/v1/resources /api/v2/resources Header Versioning (alternative): Accept: application/vnd.api.v1+json
CRUD Completeness for API
Every resource MUST have these endpoints:
typescript// 1. CREATE - Full validation POST /api/v1/products Body: { name, sku, price, categoryId, ... } Response: 201 { data: product } // 2. READ LIST - Paginated with filters GET /api/v1/products?filter[status]=active&sort=-createdAt Response: 200 { data: [...], pagination: {...} } // 3. READ DETAIL - With relationships GET /api/v1/products/:id?include=category,variants Response: 200 { data: product } // 4. UPDATE - Partial update PATCH /api/v1/products/:id Body: { price: 29.99 } Response: 200 { data: product } // 5. DELETE - Soft delete DELETE /api/v1/products/:id Response: 200 { data: { deleted: true } } // 6. RESTORE - If soft delete POST /api/v1/products/:id/restore Response: 200 { data: product }
Rate Limiting
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1620000000
API Documentation Standard
Every endpoint must document:
- Description and purpose
- Required permissions/roles
- Request body schema (with examples)
- Response schema (success + all error codes)
- Query parameters (filter, sort, include, pagination)
- Rate limit information
When NOT to Use
Do NOT use this skill when:
- Designing database schemas (use database-design skill for table structures and relationships)
- Writing application business logic (use domain-driven skill for complete business modules)
- Reviewing existing code for quality issues (use code-review skill for comprehensive audits)
- Performing security audits on APIs (use security-auditor skill for vulnerability analysis)
- Writing SQL queries for data access (use sql-best-practices skill for query optimization)
- Designing multi-page website layouts (use design-system skill for professional UI/UX and spacing)
- Analyzing deployment configurations (use deployment skill for CI/CD and infrastructure)
- Reviewing git workflows (use git-workflow skill for branching and commit conventions)
- Implementing third-party integrations (use third-party-integrations skill for external services)
