JochenYang API Designer
Design high-quality API interfaces and output standardized interface documentation and design specifications.
Core Capabilities
- RESTful/GraphQL/gRPC architecture design
- Unified naming conventions and error handling
- OpenAPI/Swagger documentation generation
- API versioning and backward compatibility
- Authentication, authorization, and rate limiting strategies
Quick Reference
HTTP Method Semantics
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Read resource | ✅ |
| POST | Create resource | ❌ |
| PUT | Full update | ✅ |
| PATCH | Partial update | ❌ |
| DELETE | Delete resource | ✅ |
Common Status Codes
200Success /201Created /204No Content400Bad Request /401Unauthorized /403Forbidden /404Not Found500Server Error
Design Principles
- Resource-Oriented: Use plural nouns in URLs, express actions with HTTP methods
- Unified Format: Consistent request/response format, structured error messages
- Version Management: URL or Header version control, backward compatibility
- Security First: Authentication, authorization, input validation, rate limiting
Boundaries
Focus on API design and documentation standards, not specific business logic implementation.
When NOT to Use
- Writing implementation code → use
developer - Database schema design → use
database-engineer - Frontend UI development → use
frontend-design - Infrastructure or DevOps setup → use
devops-engineer
When To Use
Use this skill when the user asks to:
- design a new API or endpoint structure
- document existing APIs with OpenAPI/Swagger
- plan API versioning or migration strategy
- establish authentication/authorization patterns for APIs
Quick Reference
Always run --help first to see usage.
scripts/openapi-gen.sh- Generate OpenAPI documentation
Detailed References
./workflows/api-design.md- API design workflow./guides/rest-api.md- REST API design guide./guides/graphql.md- GraphQL API design guide./guides/grpc.md- gRPC API design guide
Escalation Rules
Pause and ask the owner before:
- locking in an API style, auth model, or versioning strategy that has broad product impact
- expanding from interface design into implementation details outside this skill's boundary
- making compatibility assumptions that could break existing clients
Final Output Contract (MANDATORY)
Every use of this skill should end with:
Skill Fit- why API design work was neededPrimary Deliverable- interface design, spec, or contract summaryExecution Evidence- references used, files produced, and validation performedRisks / Open Questions- compatibility, auth, or rollout concernsNext Action- the concrete documentation, review, or implementation step