| name | api-architecture |
| author | JM Labs (Javier Montaño) |
| description | REST, GraphQL, and gRPC API governance, versioning strategy, rate limiting, and developer experience design. Trigger: "API architecture", "API design", "REST", "GraphQL", "gRPC", "API governance", "developer experience".
|
| allowed-tools | ["Read","Glob","Grep","Bash","Agent"] |
API Architecture
Design and govern APIs across the stack: REST/GraphQL/gRPC protocol selection, versioning strategies, rate limiting, security, documentation, and developer experience optimization.
Guiding Principle
"APIs are the product — every endpoint is a contract, every breaking change is a trust violation, every missing doc is a support ticket."
Procedure
Step 1 — API Style Selection & Design
- Evaluate API style per use case: REST (CRUD resources), GraphQL (flexible queries), gRPC (high-perf inter-service)
- Define resource naming conventions and URL structure
- Design request/response schemas with consistent envelope patterns
- Specify error response format: error codes, messages, field-level details
- Implement pagination strategy: cursor-based, offset-based, or keyset
Step 2 — Versioning & Evolution
- Select versioning strategy: URI path, header, query parameter, or content negotiation
- Define backward compatibility rules: additive-only for minor versions
- Design deprecation process: timeline, communication, sunset headers
- Implement API changelog generation from spec diffs
- Establish breaking change review process with consumer notification
Step 3 — Security & Rate Limiting
- Design authentication strategy per API tier: API keys, OAuth 2.0, JWT
- Implement authorization: scopes, RBAC, or ABAC per endpoint
- Design rate limiting: per-client, per-endpoint, with burst allowance
- Implement input validation and sanitization at the gateway layer
- Define CORS, CSP, and security header policies
Step 4 — Developer Experience & Governance
- Generate OpenAPI/AsyncAPI specifications from code or design-first
- Build interactive API documentation with try-it-out capabilities
- Provide SDK generation for primary consumer languages
- Design API catalog with discovery, search, and dependency tracking
- Establish API design review process with style guide enforcement
Quality Criteria
- All APIs have OpenAPI/AsyncAPI specifications with >90% endpoint coverage
- Rate limiting tested under load with documented behavior at limits
- Breaking changes go through deprecation cycle with >30-day notice
- API documentation includes runnable examples for every endpoint
Anti-Patterns
- Inconsistent naming conventions across different API surfaces
- Versioning by creating entirely new API copies instead of evolution
- Rate limiting without communicating limits in response headers
- API documentation generated but never tested or maintained