REST and GraphQL API architect for designing robust, scalable APIs. Use when designing new APIs or improving existing ones.

API Designer Expert in designing REST and GraphQL APIs that are robust, scalable, and maintainable. When This Skill Activates Activates when you: Design a new API Review API design Improve existing API Create API specifications REST API Design Principles 1. Resource Oriented Design Good: Avoid: 2. HTTP Methods Method Safe Idempotent Purpose GET ✓ ✓ Read resource POST ✗ ✗ Create resource PUT ✗ ✓ Replace resource PATCH ✗ ✗ Update resource DELETE ✗ ✓ Delete resource 3. Status Codes Code Meaning Usage 200 OK Successful GET, PATCH, DELETE 201 Created Successful POST 204 No Content Successful DELETE with no body 400 Bad Request Invalid input 401 Unauthorized Missing or invalid auth 403 Forbidden Authenticated but not authorized 404 Not Found Resource doesn't exist 409 Conflict Resource already exists 422 Unprocessable Valid syntax but semantic errors 429 Too Many Requests Rate limit exceeded 500 Internal Server Error Server error 4. Naming Conventions URLs : kebab case ( /user preferences ) JSON : camelCase ( {"userId": "123"} ) Query params : snake case or camelCase ( ?page size=10 ) 5. Pagination 6. Filtering and Sorting GraphQL API Design Schema Design Best Practices Nullability : Default to non null, nullable only when appropriate Connections : Use cursor based pagination for lists Payloads : Use mutation payloads for consistent error handling Descriptions : Document all types and fields API Versioning Approaches URL Versioning (Recommended): Header Versioning : Versioning Guidelines Start with v1 Maintain backwards compatibility when possible Deprecate old versions with notice Document breaking changes Authentication & Authorization Authentication Methods 1. JWT Bearer Token 2. API Key 3. OAuth 2.0 Authorization Use roles/permissions Document required permissions per endpoint Return 403 for authorization failures Rate Limiting Recommended limits: Public APIs: 100 1000 requests/hour Authenticated APIs: 1000 10000 requests/hour Webhooks: 10 100 requests/minute Documentation Requirements All endpoints documented Request/response examples Authentication requirements Error response formats Rate limits SDK examples (if available) Scripts Generate API scaffold: Validate API design: References references/rest patterns.md REST design patterns references/graphql patterns.md GraphQL design patterns [REST API Tutorial](https://restfulapi.net/) [GraphQL Best Practices](https://graphql.org/learn/best practices/)

api-designer