技能 api-design-principles
📦

api-design-principles

安全

Designe APIs intuitivas e escaláveis

也可从以下获取: wshobson

Criar APIs sem princípios de design consistentes leva a interfaces confusas e uma experiência ruim para desenvolvedores. Esta skill fornece padrões comprovados de REST e GraphQL para criar APIs manuteníveis e bem documentadas que escalam conforme suas necessidades.

支持: Claude Codex Code(CC)
🥈 78 白银
1

下载技能 ZIP

2

在 Claude 中上传

前往 设置 → 功能 → 技能 → 上传技能

3

开启并开始使用

测试它

正在使用“api-design-principles”。 Design endpoints for an e-commerce product catalog

预期结果:

  • GET /api/v1/products - List products with pagination
  • GET /api/v1/products/{id} - Get product details
  • POST /api/v1/products - Create product (admin only)
  • PUT /api/v1/products/{id} - Replace product (admin only)
  • PATCH /api/v1/products/{id} - Update product fields (admin only)
  • DELETE /api/v1/products/{id} - Remove product (admin only)
  • GET /api/v1/products/{id}/reviews - List product reviews
  • GET /api/v1/categories/{id}/products - List products by category

正在使用“api-design-principles”。 What HTTP status codes for common scenarios?

预期结果:

  • 200 OK - Successful GET, PUT, PATCH requests
  • 201 Created - Successful POST with resource creation
  • 204 No Content - Successful DELETE or empty response
  • 400 Bad Request - Malformed JSON or invalid syntax
  • 401 Unauthorized - Missing or expired authentication
  • 403 Forbidden - Valid auth but insufficient permissions
  • 404 Not Found - Resource does not exist
  • 409 Conflict - Resource conflict (e.g., duplicate key)
  • 422 Unprocessable Entity - Validation errors
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Unexpected server failure

安全审计

安全
v1 • 2/24/2026

Static analysis flagged 201 patterns that are all false positives. The skill contains only documentation and educational content about API design. Markdown code blocks (backticks) were incorrectly identified as shell execution. Cryptographic references appear in security checklists, not actual implementations. URL and IP references are documentation examples for API endpoints. No executable code or security risks present.

6
已扫描文件
1,886
分析行数
0
发现项
1
审计总数
未发现安全问题
审计者: claude

质量评分

55
架构
100
可维护性
87
内容
50
社区
100
安全
91
规范符合性

你能构建什么

Design de API do Zero

Designe uma nova API REST ou GraphQL do zero com modelagem adequada de recursos, estrutura de endpoints e padrões de documentação antes do início da implementação.

Revisão e Refatoração de API

Avalie endpoints de API existentes contra princípios de design para identificar inconsistências, melhorar convenções de nomenclatura e planejar estratégias de migração.

Documentação de Padrões da Equipe

Estabeleça diretrizes de design de API em toda a organização cobrindo versionamento, tratamento de erros, padrões de autenticação e formatos de resposta para alinhamento da equipe.

试试这些提示

Design Básico de Endpoint REST 
I need to design REST endpoints for a blog system with authors, posts, and comments. Help me structure the URL hierarchy, HTTP methods, and response formats following REST best practices.
Revisão de Schema GraphQL 
Review my GraphQL schema for a user management system. Check for proper use of non-null types, interface implementations, and suggest improvements for query efficiency and avoid N+1 problems.
Estratégia de Versionamento de API 
My API has breaking changes coming. Compare URL path versioning, header versioning, and query parameter approaches for my use case. Include deprecation timeline recommendations.
Design de Tratamento de Erros 
Design a consistent error response format for my REST API. Include field-level validation errors, error codes for programmatic handling, and appropriate HTTP status codes for common scenarios.

最佳实践

  • Use plural nouns for resource collections and keep URL hierarchies shallow (maximum 2-3 levels of nesting)
  • Implement consistent pagination with documented page size limits and include total count metadata in responses
  • Version APIs from the start using URL path or header versioning, and maintain a clear deprecation policy for older versions

避免

  • Using verbs in endpoints like /createUser or /getUserById instead of proper HTTP methods on resource nouns
  • Returning different response formats or field names across similar endpoints, breaking client expectations
  • Deeply nested URLs like /users/{id}/orders/{orderId}/items/{itemId}/reviews that couple resources too tightly

常见问题

Should I use REST or GraphQL for my new API?
Choose REST when you have clear resource boundaries, need strong caching, or serve simple CRUD operations. Choose GraphQL when clients need flexible data fetching, you have complex relationships, or mobile clients need to minimize requests.
How do I handle API versioning without breaking existing clients?
Start versioning from v1 at launch. For breaking changes, create v2 alongside v1. Document deprecation timelines (typically 6-12 months). Use sunset headers to notify clients of upcoming removals. Never remove versions without sufficient notice.
What pagination approach should I use for large datasets?
Use offset-based pagination (page/page_size) for simple use cases with datasets under 100k records. Use cursor-based pagination for large datasets or real-time data where consistency matters. Always enforce maximum page sizes to prevent abuse.
How do I design error responses that developers can actually use?
Include a machine-readable error code, human-readable message, and optional field-level details. Use consistent structure across all endpoints. Document all error codes in your API reference. Return validation errors as 422 with field-specific messages.
What rate limiting strategy should I implement?
Start with requests per minute per API key or IP. Include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Return 429 status with Retry-After header when exceeded. Consider tiered limits based on authentication level.
How do I handle authentication in API design?
Use Bearer tokens (JWT or opaque) in Authorization headers for most APIs. Consider API keys for server-to-server communication. Never accept credentials in URL parameters. Document token refresh flows clearly. Return 401 for authentication failures, 403 for authorization failures.

开发者详情

作者

sickn33

许可证

MIT

仓库

https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/api-design-principles

引用

main

文件结构

📁 assets/

📄 api-design-checklist.md

📄 rest-api-template.py

📁 references/

📄 graphql-schema-design.md

📄 rest-best-practices.md

📁 resources/

📄 implementation-playbook.md

📄 SKILL.md