api-patterns
Faz seu agente decidir as melhores formas de projetar APIs. Ele ajuda a escolher entre REST, GraphQL e outros, e como organizar as respostas.
O que ela faz
Este guia ajuda você a tomar decisões importantes sobre como construir a 'linguagem' (API) que diferentes programas de computador usam para conversar entre si. Ele te ensina a escolher o melhor estilo (como REST ou GraphQL) e a definir como os dados são enviados e recebidos.
Quando usar
- ✓Ao decidir se usa REST, GraphQL ou outra forma de comunicação.
- ✓Ao definir como os dados serão devolvidos pelos programas.
- ✓Ao planejar como o sistema vai lidar com muitos acessos ou atualizações.
Exemplo do que pedir para a IA
“Como devo projetar a resposta de uma API para que ela seja fácil de usar e segura?”
Quer saber mais? Abra as seções abaixo.
Como usar
O jeito mais fácil: copie a mensagem abaixo e cole no Claude, ChatGPT, Cursor ou outra IA. Ela lê a skill e segue as instruções.
Link da skill
Mensagem pronta para colar
Como funciona
O guia oferece um 'mapa' para encontrar as informações certas sobre cada tipo de API e suas regras. Ele te faz pensar nas necessidades de quem vai usar a API antes de decidir.
Instalação
Jeito mais fácil: copie o link da skill e cole no Claude, ChatGPT ou Cursor pedindo para seguir as instruções.
No terminal (Claude Code, Codex, Cursor), na pasta do projeto:
npx skills add sickn33/agentic-awesome-skills --skill api-patternsOu baixe só o arquivo:
curl -L https://raw.githubusercontent.com/sickn33/agentic-awesome-skills/main/plugins/agentic-awesome-skills-claude/skills/api-patterns/SKILL.md -o SKILL.mdConteúdo técnico (SKILL.md)
Tradução do texto original do autor no GitHub. Os comandos e códigos estão como no original.
Padrões de API
Decisões de design de API atreladas aos consumidores e restrições de implantação. Aprenda a PENSAR, não a copiar padrões fixos.
🎯 Regra de Leitura Seletiva
Leia APENAS arquivos relevantes para a solicitação! Verifique o mapa de conteúdo, encontre o que você precisa.
📑 Mapa de Conteúdo
| Arquivo | Descrição | Quando Ler |
|---|---|---|
api-style.md |
Árvore de decisão REST vs GraphQL vs tRPC | Ao escolher o tipo de API |
rest.md |
Nomenclatura de recursos, métodos HTTP, códigos de status | Ao projetar API REST |
response.md |
Padrão de envelope, formato de erro, paginação | Estrutura de resposta |
graphql.md |
Design de schema, quando usar, segurança | Ao considerar GraphQL |
trpc.md |
Monorepo TypeScript, segurança de tipos | Projetos fullstack TS |
versioning.md |
Versionamento de URI/Header/Query | Planejamento de evolução da API |
auth.md |
JWT, OAuth, Passkey, Chaves de API | Seleção de padrão de autenticação |
rate-limiting.md |
Token bucket, janela deslizante | Proteção de API |
documentation.md |
Boas práticas OpenAPI/Swagger | Documentação |
security-testing.md |
OWASP API Top 10, testes de autenticação/autorização | Auditorias de segurança |
🔗 Habilidades Relacionadas
| Necessidade | Habilidade |
|---|---|
| Implementação de API | @[skills/backend-architect] |
| Estrutura de dados | @[skills/database-design] |
| Detalhes de segurança | @[skills/api-security-best-practices] |
✅ Checklist de Decisão
Antes de projetar uma API:
- Perguntou ao usuário sobre os consumidores da API?
- Escolheu o estilo de API para ESTE contexto? (REST/GraphQL/tRPC)
- Definiu um formato de resposta consistente?
- Planejou uma estratégia de versionamento?
- Considerou as necessidades de autenticação?
- Planejou o rate limiting?
- Definiu a abordagem de documentação?
❌ Anti-Padrões
NÃO:
- Usar REST como padrão para tudo
- Usar verbos em endpoints REST (/getUsers)
- Retornar formatos de resposta inconsistentes
- Expor erros internos para clientes
- Ignorar o rate limiting
FAÇA:
- Escolher o estilo de API com base no contexto
- Perguntar sobre os requisitos do cliente
- Documentar detalhadamente
- Usar códigos de status apropriados
Script
| Script | Propósito | Comando |
|---|---|---|
scripts/api_validator.py |
Análise local de fontes heurísticas (não validação de schema) | python3 skills/api-patterns/scripts/api_validator.py <project_path> |
Quando Usar
Use ao definir um novo contrato de endpoint, selecionar REST/GraphQL/tRPC para consumidores conhecidos, ou alterar o comportamento de paginação, erros, autenticação ou compatibilidade. Para um bug dentro de um contrato existente, preserve esse contrato a menos que a tarefa autorize uma mudança.
Entradas e procedimento
Registre consumidores e versões implantadas, tamanho esperado do payload, regras de acesso, obrigações de compatibilidade e uma operação concreta. Leia os arquivos relevantes no mapa, compare as escolhas realistas e, em seguida, especifique exemplos de requisição/resposta e casos de rejeição. Tipos compartilhados no momento da compilação não garantem que clientes implantados independentemente permaneçam compatíveis.
Exemplo prático
Entrada: uma lista pública de pedidos muda enquanto os clientes a percorrem. Escolha um tamanho de página limitado e um cursor em vez de uma ordem estável (created_at, id). Defina o formato do próximo cursor, o filtro de autorização e o comportamento para um registro removido ou cursor inválido. Teste dois timestamps iguais e uma inserção entre páginas. Esperado: sem IDs duplicados dentro das semânticas de snapshot prometidas; documente se linhas recém-inseridas podem aparecer.
Limitações
- O helper Python escaneia no máximo 15 arquivos correspondentes usando expressões regulares e verificações superficiais de JSON/YAML. Sua saída é uma dica de triagem, não validação OpenAPI, auditoria de autorização ou aprovação de implantação.
- A forma da consulta GraphQL, a inferência tRPC e os nomes dos métodos HTTP não impõem autorização de recursos ou compatibilidade retroativa.
- O rate limiting sozinho não pode prevenir todo o esgotamento de recursos; limites de tamanho, concorrência, tempo e custo do provedor dependem da operação.
- Realize verificações de segurança apenas contra alvos locais/de teste autorizados com contas isoladas e um escopo definido.
Perguntas frequentes
O que é uma API?
API é como um cardápio em um restaurante. Ele diz quais pratos (informações ou ações) estão disponíveis e como pedi-los, sem que você precise saber como a cozinha (o programa) funciona.
REST vs GraphQL vs tRPC, qual escolher?
Cada um tem suas vantagens. REST é comum e simples, GraphQL é flexível para buscar dados específicos, e tRPC é bom para projetos que usam TypeScript e precisam de segurança de tipos.
Por que a versão da API é importante?
A versão garante que mudanças futuras na 'linguagem' da API não quebrem os programas que já a utilizam. É como lançar uma nova versão de um aplicativo sem estragar as funcionalidades antigas.
Detalhes
Descrição original do autor
API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
Popularidade
- Estrelas no GitHub
- 48 mil
- Posição no ranking
- #2162
- Licença
- MIT
- Atualizada em
- 15/10/2026
Comentários
- …
Mais skills deste repositório
00-andruia-consultant
Ajuda seu agente a iniciar ou melhorar projetos de IA. Ele analisa código, sugere ferramentas e cria planos de ação em espanhol.
sickn33/agentic-awesome-skills
007
Faz seu agente realizar auditorias de segurança e modelagem de ameaças. É útil para proteger projetos contra ataques e vulnerabilidades.
sickn33/agentic-awesome-skills
10-andruia-skill-smith
Ajuda seu agente a criar ou melhorar ferramentas de IA. Ele define como as ferramentas funcionam, escreve a documentação e valida a estrutura.
sickn33/agentic-awesome-skills
20-andruia-niche-intelligence
Faz seu agente criar um resumo sobre um setor específico. É útil para entender o contexto, regras, padrões de uso e riscos de um projeto, usando fontes confiáveis.
sickn33/agentic-awesome-skills
Skills parecidas
api-connector-builder
Faz seu agente construir novas conexões com APIs seguindo o padrão já existente. Use quando precisar adicionar mais uma integração sem criar um novo jeito de fazer.
affaan-m/ECC
api-design
Ajuda seu agente a projetar APIs REST seguindo as melhores práticas. É útil para definir como as APIs se comunicam, como os erros são mostrados e como organizar os dados.
affaan-m/ECC
backend-patterns
Ajuda seu agente com padrões de arquitetura do lado do servidor e otimização de banco de dados. É útil para construir ou revisar o código que roda no servidor.
affaan-m/ECC