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

Common Status Codes

• 200 Success / 201 Created / 204 No Content
• 400 Bad Request / 401 Unauthorized / 403 Forbidden / 404 Not Found
• 500 Server Error

Design Principles

1. Resource-Oriented: Use plural nouns in URLs, express actions with HTTP methods
2. Unified Format: Consistent request/response format, structured error messages
3. Version Management: URL or Header version control, backward compatibility
4. Security First: Authentication, authorization, input validation, rate limiting

Boundaries

Focus on API design and documentation standards, not specific business logic implementation.

Helper Scripts

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