api-design-framework

# API Design Framework

This skill provides comprehensive guidance for designing robust, scalable, and developer-friendly APIs. Whether building REST, GraphQL, or gRPC services, this framework ensures consistency, usability, and maintainability.

## Overview
- Designing new API endpoints or services
- Establishing API conventions for a team or organization
- Reviewing API designs for consistency and best practices
- Migrating or versioning existing APIs
- Creating API documentation (OpenAPI, AsyncAPI)
- Choosing between REST, GraphQL, or gRPC

## API Design Principles

### 1. Developer Experience First
APIs should be intuitive and self-documenting:
- Clear, consistent naming conventions
- Predictable behavior and responses
- Comprehensive documentation
- Helpful error messages

### 2. Consistency Over Cleverness
Follow established patterns rather than inventing new ones:
- Standard HTTP methods and status codes (REST)
- Conventional query structures (GraphQL)
- Idiomatic proto definitions (gRPC)

### 3. Evolution Without Breaking Changes
Design for change from day one:
- API versioning strategy
- Backward compatibility considerations
- Deprecation policies
- Migration paths

### 4. Performance by Design
Consider performance implications:
- Pagination for large datasets
- Filtering and partial responses
- Caching strategies
- Rate limiting

---

## Bundled Resources

- `assets/openapi-template.yaml` - OpenAPI 3.1 specification template
- `assets/asyncapi-template.yaml` - AsyncAPI specification template
- `references/rest-api.md` - REST API design patterns
- `references/graphql-api.md` - GraphQL API design patterns
- `references/grpc-api.md` - gRPC API design patterns
- `references/frontend-integration.md` - Frontend API integration patterns

---

## Protocol References

### REST API Design
**See: `references/rest-api.md`**

Key topics covered:
- Resource naming conventions (plural nouns, hierarchical relationships)
- HTTP methods (GET, POST, PUT, PATCH, DELETE)
- Sta