Api Specification Design

---
name: api-specification-design
description: "Use when designing API specifications."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [api, specification, design, openapi]
    related_skills: ['api-design-and-documentation', 'swagger-openapi-patterns']
---

## Overview
Design API specifications using OpenAPI, Swagger, and GraphQL schemas with proper versioning and documentation.

## When to Use
- "API specification design and implementation"
- "Best practices for API documentation"
- "API specification optimization"
- "API specification troubleshooting"

## Key Approaches
1. Define clear requirements and specifications
2. Choose appropriate frameworks and tools
3. Implement with modular, maintainable structure
4. Write comprehensive tests and validate
5. Document architecture and decisions
6. Monitor and iterate based on feedback

## Common Pitfalls
1. **Not accounting for constraints** — resource limitations
2. **Ignoring industry standards** — no best practices followed
3. **Poor stakeholder alignment** — conflicting requirements
4. **Inadequate testing** — no validation of functions
5. **Not documenting decisions** — lost knowledge transfer
6. **Over-engineering** — complex where simple suffices
7. **No rollback plan** — deployment failures
8. **Insufficient monitoring** — no observability
9. **Not planning for growth** — scalability issues
10. **Missing validation** — no quality checks

## Verification Checklist
- [ ] Requirements defined and validated
- [ ] Standards and best practices applied
- [ ] Design reviewed with stakeholders
- [ ] Implementation plan with milestones
- [ ] Testing strategy defined
- [ ] Documentation complete
- [ ] Monitoring and alerting configured
- [ ] Deployment with rollback plan
- [ ] Security review completed
- [ ] Post-deployment verification