Habilidades api-design-principles

🧭

api-design-principles

Name: api-design-principles
Author: wshobson

Seguro 🌐 Acesso à rede⚙️ Comandos externos

Projete APIs REST e GraphQL com confiança

As decisões de design de API frequentemente se tornam inconsistentes e difíceis de manter. Esta skill fornece padrões claros, templates e checklists para orientar suas escolhas.

Suporta: Claude Codex Code(CC)

🥉 72 Bronze

Baixar o ZIP da skill

Upload no Claude

Vá em Configurações → Capacidades → Skills → Upload skill

Ative e comece a usar

Testar

A utilizar "api-design-principles". Revise meus endpoints de usuários e pedidos para práticas recomendadas de REST.

Resultado esperado:

Use substantivos plurais: /api/users e /api/orders
Substitua caminhos de ação como /api/createUser por POST /api/users
Adicione paginação a endpoints de lista com page e page_size
Retorne 201 Created em POST bem-sucedido e 204 em DELETE

A utilizar "api-design-principles". Como devo estruturar um schema GraphQL para um blog com usuários, posts e comentários?

Resultado esperado:

Defina tipos User, Post, Comment com relacionamentos adequados
Use paginação por cursor estilo Relay para coleções
Crie tipos de entrada para mutations com payloads de erro
Adicione DataLoaders para prevenir queries N+1 em relacionamentos

A utilizar "api-design-principles". Quais códigos de status minha API deve retornar para erros de validação?

Resultado esperado:

Retorne 400 Bad Request para sintaxe de request malformada
Retorne 422 Unprocessable Entity para falhas de validação
Inclua detalhes de erro em nível de campo no corpo da resposta
Use formato de erro consistente em todos os endpoints

Auditoria de Segurança

Seguro

v4 • 1/17/2026

This skill contains only educational documentation, code templates, and best practices for API design. All 233 static findings are false positives: 'weak cryptographic algorithm' flags educational password hashing examples; 'backtick execution' misinterprets markdown code formatting; 'system reconnaissance' triggers on legitimate programming terms like fetch/decode; hardcoded URLs/IPs are documentation examples, not actual network calls. No executable code, network calls, or data access patterns pose security risks.

Arquivos analisados

2,011

Linhas analisadas

achados

Total de auditorias

Fatores de risco

🌐 Acesso à rede (7)

assets/rest-api-template.py:182 references/rest-best-practices.md:132 references/rest-best-practices.md:133 references/rest-best-practices.md:134 references/rest-best-practices.md:135 references/rest-best-practices.md:324 skill-report.json:6

⚙️ Comandos externos (134)

Auditado por: claude Ver Histórico de Auditoria →

Pontuação de qualidade

Arquitetura

Manutenibilidade

Conteúdo

Comunidade

100

Segurança

Conformidade com especificações

O Que Você Pode Construir

Definir novos padrões de API

Crie regras consistentes de REST e GraphQL para uma equipe antes da implementação.

Revisar especificações de API

Audite especificações para problemas de nomenclatura, versionamento e tratamento de erros.

Melhorar usabilidade de API

Refine endpoints e schema para reduzir confusão e retrabalho dos clientes.

Tente Estes Prompts

Revisão de conceitos básicos de REST

Revise este outline de API REST e liste correções de nomenclatura, método e código de status. Forneça um exemplo corrigido curto.

Verificação de schema GraphQL

Avalie este schema GraphQL para paginação, tipos de entrada e padrões de erro. Sugira melhorias com breves exemplos.

Estratégia de versionamento

Recomende uma abordagem de versionamento para esta API e explique os tradeoffs. Forneça um checklist de migração.

Execução de checklist de design

Aplique um checklist de design de API a esta especificação e retorne passa ou falha com correções para cada item falho.

Melhores Práticas

Documente regras de versionamento e deprecação antes do lançamento
Use formatos de erro consistentes com códigos de erro estáveis
Paginate todos os endpoints de coleção com limites claros

Evitar

Usar POST para operações somente de leitura
Caminhos de recursos aninhados além de dois níveis
Retornar formas de erro inconsistentes entre endpoints

Perguntas Frequentes

Isso é compatível com Claude, Codex e Claude Code?

Sim. A orientação é agnóstica de plataforma e funciona em Claude, Codex e Claude Code.

Quais são os limites desta skill?

Fornece padrões e templates mas não gera um serviço de API completo funcionando.

Posso integrar isso com minha base de código existente?

Sim. Use o checklist e templates para alinhar seus endpoints e schema existentes.

Ele acessa ou armazena dados sensíveis?

Não. Apenas fornece orientação e exemplos estáticos.

E se meu design de API não for coberto?

Forneça sua especificação e objetivos, então peça recomendações direcionadas.

Como isso se compara a conselhos genéricos de API?

Inclui padrões concretos de REST e GraphQL com checklists e templates.

Detalhes do Desenvolvedor

Autor

wshobson

Licença

NOASSERTION

Repositório

https://github.com/wshobson/agents/tree/main/plugins/backend-development/skills/api-design-principles

Referência

main

Estrutura de arquivos

📁 assets/

📄 api-design-checklist.md

📄 rest-api-template.py

📁 references/

📄 graphql-schema-design.md

📄 rest-best-practices.md

📄 SKILL.md