api-design
Define standards and best practices for designing secure, consistent, scalable, and maintainable APIs across all services.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- api-design
- author
- AI Business OS
- license
- MIT
- version
- 1.0.0
- category
- shared
- priority
- required
- description
- Define standards and best practices for designing secure, consistent, scalable, and maintainable APIs across all services.
02 资源文件 1
- 参考文档README.md134 B
03 SKILL.md 正文
API Design
Purpose
This skill defines API design standards that ensure consistency, usability, security, scalability, and maintainability across all services.
The goal is to create APIs that are intuitive for developers, resilient in production, and easy to evolve over time.
When to Use
Execute when:
- Designing new REST APIs
- Designing GraphQL APIs
- Creating internal service APIs
- Creating public APIs
- Reviewing API contracts
- Versioning existing APIs
Objectives
Design APIs that are:
- Consistent
- Predictable
- Secure
- Versioned
- Scalable
- Easy to consume
Inputs
Expected inputs:
- Business Requirements
- Product Requirements
- User Stories
- Data Models
- Security Requirements
- Integration Requirements
API Design Principles
Follow these principles:
- Resource-oriented design
- Consistent naming
- Stateless communication
- Idempotent operations where applicable
- Backward compatibility
- Explicit versioning
Resource Design
Define:
- Resources
- Collections
- Relationships
- Nested Resources
- Resource Identifiers
Use nouns instead of verbs for resource names.
Examples:
- /users
- /orders
- /products/{id}
HTTP Methods
Use methods appropriately:
- GET — Retrieve resources
- POST — Create resources
- PUT — Replace resources
- PATCH — Partial updates
- DELETE — Remove resources
Avoid using GET for state-changing operations.
Request Design
Document:
- Headers
- Query Parameters
- Path Parameters
- Request Body
- Validation Rules
- Required Fields
Ensure all inputs are validated.
Response Design
Responses should include:
- HTTP Status Code
- Response Body
- Metadata
- Pagination
- Error Details
Maintain a consistent response structure across all APIs.
Error Handling
Standardize:
- Error Codes
- Error Messages
- Validation Errors
- Authentication Errors
- Authorization Errors
- Server Errors
Error messages should be actionable and never expose sensitive information.
Authentication & Security
Support:
- OAuth 2.0
- OpenID Connect
- JWT Bearer Tokens
- API Keys
- Mutual TLS (where required)
Apply authorization checks to every protected endpoint.
Versioning
Support:
- URI Versioning
- Header Versioning
- Semantic Versioning
Document deprecation and migration strategies.
Pagination & Filtering
For collections support:
- Pagination
- Sorting
- Filtering
- Search
Avoid returning unbounded result sets.
Validation Checklist
Before completion verify:
- Resources consistently named
- HTTP methods correctly applied
- Request schema defined
- Response schema defined
- Error responses standardized
- Security requirements implemented
- Versioning strategy documented
Failure Conditions
Stop and request clarification if:
- Resources are undefined
- API purpose is unclear
- Security requirements are missing
- Response format is inconsistent
- Versioning strategy is absent
Outputs
Generate:
- API Design Specification
- Endpoint Catalog
- Request/Response Standards
- Error Catalog
- Versioning Strategy
Rules
- Prefer consistency over creativity.
- Design APIs around resources.
- Keep endpoints predictable.
- Never expose internal implementation details.
- Design for backward compatibility whenever possible.
Success Criteria
This skill succeeds when:
- APIs are easy to understand
- integrations are reliable
- security is consistently applied
- breaking changes are minimized
- documentation matches implementation
Related Skills
- authentication
- authorization
- security
- database
- validation
Version History
| Version | Date | Description |
|---|---|---|
| 1.0.0 | 2026-07-10 | Initial release |
04 同仓库更多 Skills
rollback
Plan, validate, and execute safe rollback procedures to restore a stable system state when deployments introduce critical issues.
release-note
Create clear, concise, and stakeholder-friendly release notes that communicate new features, improvements, fixes, breaking changes, and operational guidance for each release.
monitoring
Continuously observe application health, performance, reliability, and business metrics after deployment to detect issues early and support operational excellence.
maintenance
Maintain, improve, and support production systems after release through continuous monitoring, issue resolution, updates, and operational excellence.
deployment
Plan, validate, and execute application deployments safely and consistently across environments while minimizing downtime and deployment risk.
changelog
Maintain a structured, accurate, and versioned changelog that records all notable changes made to the project across releases.