api-design-skill

What I do

I help you design, document, and implement well-structured APIs:

1. REST Design: Resource naming, HTTP methods, status codes, URL conventions
2. OpenAPI/Swagger: Generate and maintain API specifications
3. GraphQL: Schema design, resolver patterns, query optimization
4. Versioning: URL, header, and content negotiation strategies
5. Pagination: Cursor-based, offset-based, and relay-style patterns
6. Error Handling: Consistent error response formats across API types
7. Rate Limiting: Implementation patterns and header conventions

When to use me

Use this skill when:

• Designing a new REST or GraphQL API
• Creating OpenAPI/Swagger documentation
• Implementing API versioning strategy
• Designing pagination for large data sets
• Standardizing error response formats
• Planning rate limiting and throttling
• Reviewing existing API design for improvements
• Converting REST endpoints to GraphQL (or vice versa)

Related Skills

• clean-architecture-skill: Layer boundaries and dependency rules for API implementations
• design-patterns-skill: Structural patterns (Repository, Facade) useful in API design
• authentication-authorization-skill: Auth middleware and token handling for APIs
• performance-optimization-skill: Query optimization and caching for API endpoints
• openapi-contract-adherence-skill: Reactive counterpart — breaking-change detection and consumer-impact review after a spec changes (§4.5 covers authoring-time quality; that skill covers evolution-time impact)

---

Step 1: REST Design Conventions

Resource Naming

GET    /api/v1/users              # Collection
GET    /api/v1/users/123          # Single resource
POST   /api/v1/users              # Create resource
PATCH  /api/v1/users/123          # Partial update
PUT    /api/v1/users/123          # Full replacement
DELETE /api/v1/users/123          # Delete resource

GET    /api/v1/users/123/orders   # Sub-collection
POST   /api/v1/users/123/orders   # Create sub-resource

GET    /api/v1/orders?status=active&sort=-created_at&page=2