api-developer
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAPI Developer
API开发者
Core Workflow
核心工作流程
- Analyze Requirements: Understand the business needs and define the API endpoints required.
- Design API: Create API designs that follow RESTful principles and best practices.
- Implement Endpoints: Develop the API endpoints with appropriate HTTP methods and status codes.
- Secure API: Implement authentication and authorization mechanisms.
- Document API: Use OpenAPI/Swagger to document the API endpoints, request/response formats, and error codes.
- Test API: Perform thorough testing to ensure functionality, security, and performance.
- Monitor API: Set up monitoring to track API usage, performance, and errors.
- Maintain API: Regularly update the API to fix bugs, improve performance, and add new features.
- Version API: Implement versioning strategies to manage breaking changes.
- 分析需求：理解业务需求，定义所需的API端点。
- 设计API：遵循RESTful原则和最佳实践创建API设计方案。
- 实现端点：使用合适的HTTP方法和状态码开发API端点。
- API安全防护：实现身份验证和授权机制。
- API文档编写：使用OpenAPI/Swagger记录API端点、请求/响应格式以及错误码。
- API测试：执行全面测试，确保功能、安全性和性能达标。
- API监控：设置监控以跟踪API的使用情况、性能和错误信息。
- API维护：定期更新API以修复漏洞、提升性能并添加新功能。
- API版本管理：实施版本控制策略，管理破坏性变更。
Reference Guide
参考指南
Load the detailed guidance based on on context:
| Topic | Reference | Load When |
|---|---|---|
| HTTP Methods | references/01-http-methods.md | When deciding on appropriate HTTP methods for endpoints |
| Resource Naming | references/02-resource-naming.md | When naming API endpoints and structuring URL hierarchies |
| Versioning | references/03-versioning.md | When planning breaking changes or deprecating API versions |
| Status Codes | references/04-status-codes.md | When choosing HTTP status codes for responses |
| Filtering & Pagination | references/05-filtering-pagination.md | When implementing list endpoints with filtering, sorting, or pagination |
| Response Shape | references/06-response-shape.md | When structuring JSON response envelopes for data and errors |
| Including Related Data | references/07-including-related-data.md | When implementing optional expansion of related resources |
| Field Naming | references/08-field-naming.md | When defining field names in request/response payloads |
| Datetime Handling | references/09-datetime-handling.md | When working with dates and times in API payloads |
| Authentication & Tokens | references/10-authentication-tokens.md | When implementing authentication or token management |
| Rate Limiting | references/11-rate-limiting.md | When implementing request throttling or abuse prevention |
| Security Basics | references/12-security-basics.md | When reviewing API security or handling untrusted input |
| Validation Errors | references/13-validation-errors.md | When formatting validation error responses |
| Caching | references/14-caching.md | When implementing HTTP caching for GET endpoints |
| Idempotency | references/15-idempotency.md | When ensuring safe retries for mutating operations |
| Error Handling | references/16-error-handling.md | When mapping exceptions to API error responses |
| Documentation | references/17-documentation.md | When creating or updating OpenAPI specs |
| Deprecation | references/18-deprecation.md | When planning to retire or replace API endpoints |
| Consistency Rules | references/19-consistency-rules.md | When reviewing API design for style guide compliance |
| Pre-Release Checklist | references/20-pre-release-checklist.md | Before releasing a new API or major endpoint |
根据上下文加载详细指南：
| 主题 | 参考链接 | 加载时机 |
|---|---|---|
| HTTP方法 | references/01-http-methods.md | 为端点选择合适的HTTP方法时 |
| 资源命名 | references/02-resource-naming.md | 为API端点命名和构建URL层级结构时 |
| 版本管理 | references/03-versioning.md | 规划破坏性变更或弃用API版本时 |
| 状态码 | references/04-status-codes.md | 为响应选择HTTP状态码时 |
| 过滤与分页 | references/05-filtering-pagination.md | 实现带有过滤、排序或分页功能的列表端点时 |
| 响应结构 | references/06-response-shape.md | 为数据和错误构建JSON响应包时 |
| 关联数据包含 | references/07-including-related-data.md | 实现关联资源的可选扩展功能时 |
| 字段命名 | references/08-field-naming.md | 定义请求/响应负载中的字段名称时 |
| 日期时间处理 | references/09-datetime-handling.md | 在API负载中处理日期和时间时 |
| 身份验证与令牌 | references/10-authentication-tokens.md | 实现身份验证或令牌管理功能时 |
| 请求限流 | references/11-rate-limiting.md | 实现请求限流或滥用防护功能时 |
| 安全基础 | references/12-security-basics.md | 审查API安全性或处理不可信输入时 |
| 验证错误处理 | references/13-validation-errors.md | 格式化验证错误响应时 |
| 缓存 | references/14-caching.md | 为GET端点实现HTTP缓存时 |
| 幂等性 | references/15-idempotency.md | 确保变更操作可安全重试时 |
| 错误处理 | references/16-error-handling.md | 将异常映射为API错误响应时 |
| 文档编写 | references/17-documentation.md | 创建或更新OpenAPI规范时 |
| 弃用管理 | references/18-deprecation.md | 规划停用或替换API端点时 |
| 一致性规则 | references/19-consistency-rules.md | 审查API设计是否符合风格指南时 |
| 发布前检查清单 | references/20-pre-release-checklist.md | 发布新API或主要端点之前 |
Constraints
约束条件
MUST DO
必须执行的操作
- Must follow RESTful principles and best practices.
- Ensure all endpoints are secure and protected against common vulnerabilities.
- Document all API endpoints clearly using OpenAPI/Swagger.
- Implement proper error handling and return meaningful status codes.
- Monitor API performance and set up alerts for downtime or errors.
- 必须遵循RESTful原则和最佳实践。
- 确保所有端点都是安全的，可抵御常见漏洞。
- 使用OpenAPI/Swagger清晰记录所有API端点。
- 实现完善的错误处理机制，返回有意义的状态码。
- 监控API性能，为停机或错误设置告警。
MUST NOT DO
禁止执行的操作
- Expose sensitive data through the API.
- Implement breaking changes without proper versioning.
- Ignore performance optimization opportunities.
- Overcomplicate API designs; keep them simple and intuitive.
- Neglect testing; ensure all endpoints are thoroughly tested before deployment.
- 通过API暴露敏感数据。
- 未进行适当版本管理就实施破坏性变更。
- 忽视性能优化的机会。
- 过度复杂化API设计；保持设计简洁直观。
- 忽略测试环节；确保所有端点在部署前都经过全面测试。