api-design
REST和GraphQL API设计最佳实践,包括HTTP方法、状态码和文档。
📖 中文导读:REST和GraphQL API设计最佳实践,包括HTTP方法、状态码和文档。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: api-design description: REST and GraphQL API design best practices including HTTP methods, status codes, and documentation. globs: ["/routes/", "/api/", "/graphql/", "**/schema.graphql"] priority: 85 tags: ["workflow"]
API Design Best Practices
REST API Design
- Use nouns for resources (/users, /orders)
- Use HTTP methods correctly (GET, POST, PUT, DELETE)
- Use proper status codes
- Version your API (/v1/users)
- Use plural nouns
HTTP Status Codes
- 200 OK - Success
- 201 Created - Resource created
- 204 No Content - Deletion success
- 400 Bad Request - Client error
- 401 Unauthorized - Authentication required
- 403 Forbidden - Not allowed
- 404 Not Found - Resource not found
- 500 Internal Server Error - Server error
Request/Response
- Use JSON consistently
- Use camelCase for field names
- Include error details in responses
- Implement pagination for lists
- Use HATEOAS for discoverability
GraphQL
- Define clear schema
- Use fragments for reuse
- Implement proper error handling
- Use DataLoader for N+1
- Implement query complexity limits
Documentation
- Use OpenAPI/Swagger for REST
- Document all endpoints
- Include request/response examples
- Document error responses
- Keep docs in sync with code
Versioning
- Use URL versioning (/v1/)
- Or use header versioning
- Maintain backward compatibility
- Deprecate gracefully