api-designer
Expert API architecture including REST, GraphQL, gRPC design, versioning, and documentation
When & Why to Use This Skill
The API Designer skill provides expert-level guidance for architecting robust, scalable, and maintainable APIs. It covers the full lifecycle of API development, from resource modeling and protocol selection (REST, GraphQL, gRPC) to documentation with OpenAPI and implementation of security best practices, ensuring high-performance communication between software components.
Use Cases
- Designing a RESTful resource model for complex business systems with proper URL structures and HTTP method semantics.
- Developing a type-safe GraphQL schema with optimized queries and subscriptions for modern web applications.
- Defining high-performance internal microservices using gRPC and Protocol Buffers for low-latency communication.
- Establishing API versioning and deprecation strategies to ensure backward compatibility during system evolution.
- Creating comprehensive API documentation using OpenAPI 3.0 or GraphQL SDL to improve developer experience and integration speed.
- Configuring API Gateway patterns including rate limiting, authentication, and request transformation for secure infrastructure.
| name | api-designer |
|---|---|
| description | Expert API architecture including REST, GraphQL, gRPC design, versioning, and documentation |
| version | 1.0.0 |
| author | USER |
| tags | [api, rest, graphql, grpc, design, versioning] |
API Designer
Purpose
Design robust, scalable APIs including REST, GraphQL, and gRPC with proper versioning, documentation, and evolution strategies.
Activation Keywords
- API design, API architecture
- REST design, GraphQL schema
- gRPC, Protocol Buffers
- API versioning, deprecation
- API gateway
Core Capabilities
1. REST API Design
- Resource modeling
- URL structure
- HTTP methods semantics
- Status codes
- HATEOAS
2. GraphQL
- Schema design
- Type system
- Query optimization
- Subscription design
- Federation
3. gRPC
- Service definition
- Message design
- Streaming patterns
- Error handling
- Interceptors
4. API Gateway
- Routing
- Rate limiting
- Authentication
- Request transformation
- Response aggregation
5. Documentation
- OpenAPI 3.0
- GraphQL SDL
- Protocol Buffers
- API changelog
Design Principles
1. Consistency
- Naming conventions
- Error formats
- Response structures
2. Evolvability
- Versioning strategy
- Backward compatibility
- Deprecation policy
3. Security
- Authentication
- Authorization
- Input validation
4. Performance
- Pagination
- Filtering
- Field selection
- Caching headers
API Design Checklist
## Endpoint Design
- [ ] Resources properly named (nouns, plural)
- [ ] Correct HTTP methods used
- [ ] Consistent URL structure
- [ ] Query params for filtering/sorting
## Response Design
- [ ] Consistent response envelope
- [ ] Proper status codes
- [ ] Error format standardized
- [ ] Pagination metadata included
## Security
- [ ] Authentication documented
- [ ] Authorization rules clear
- [ ] Rate limits defined
- [ ] Input validation rules
## Documentation
- [ ] All endpoints documented
- [ ] Examples for each endpoint
- [ ] Error codes documented
- [ ] Versioning strategy documented
Protocol Selection Guide
| Need | Recommendation |
|---|---|
| Public API | REST + OpenAPI |
| Frontend flexibility | GraphQL |
| Internal microservices | gRPC |
| Real-time | WebSocket/GraphQL Subscriptions |
| High throughput | gRPC |
Example Usage
User: "Design API for a booking system"
API Designer Response:
1. Resource identification
- /bookings, /users, /properties, /availability
2. Endpoint design
- POST /bookings (create)
- GET /properties/{id}/availability
- PATCH /bookings/{id}/cancel
3. GraphQL alternative schema
4. Authentication strategy (OAuth2)
5. Versioning strategy (URL-based /v1/)
6. OpenAPI specification