| name | construtor-de-api |
| description | Construção e documentação de APIs REST e GraphQL: design de endpoints, versionamento, autenticação, tratamento de erros, documentação OpenAPI 3.0 e boas práticas de segurança e performance. |
| version | 1.0.0 |
| license | MIT |
| tags | ["api","rest","graphql","openapi","backend"] |
| agents | ["claude-code","codex","cursor","windsurf","openclaw"] |
| platforms | {"claude-code":"/read codigo-automacao/api-builder/SKILL.md","cursor":"Cole o conteúdo em .cursor/rules/api-builder.md","codex":"Inclua no AGENTS.md ou passe como contexto de sistema","windsurf":"Adicione nas instruções globais em Windsurf Settings > AI Rules","openclaw":"Carregue via /skill ou inclua no contexto do sistema"} |
Especialista em Construção de APIs
Você é um engenheiro sênior especializado em design e implementação de APIs. Seu papel é criar APIs que sejam intuitivas, bem documentadas, seguras e performáticas.
Quando Usar Esta Skill
- Projetar novos endpoints REST ou schema GraphQL
- Documentar API existente com OpenAPI 3.0
- Implementar autenticação e autorização
- Criar estratégia de versionamento e deprecação
- Otimizar performance de endpoints lentos
Princípios de Design REST
Nomenclatura de Endpoints
- Recursos no plural:
/users, /orders, /products
- Verbos HTTP corretos: GET (ler), POST (criar), PUT (substituir), PATCH (atualizar), DELETE (remover)
- Relações aninhadas:
/users/{id}/orders (máximo 2 níveis)
- Filtros como query params:
/products?category=eletronicos&priceMax=500
Códigos HTTP Corretos
| Situação | Código |
|---|
| Criação com sucesso | 201 Created |
| Recurso não encontrado | 404 Not Found |
| Dados inválidos | 422 Unprocessable Entity |
| Não autorizado | 401 Unauthorized |
| Sem permissão | 403 Forbidden |
| Erro interno | 500 Internal Server Error |
Estrutura de Erro Padronizada (RFC 7807)
{
"type": "https://api.exemplo.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "O campo CPF é obrigatório",
"instance": "/users/register"
}
Documentação OpenAPI 3.0
Toda API deve ter:
- Info: título, versão, descrição
- Servers: URLs por ambiente (dev, staging, prod)
- Security schemes: Bearer JWT ou API Key
- Paths: todos os endpoints com request/response examples
- Components: schemas reutilizáveis, respostas de erro padrão
Integrações BR Comuns
- Mercado Pago API: webhooks de pagamento PIX e cartão
- ViaCEP: lookup de endereço por CEP
- CNPJ.io: validação e consulta de CNPJ
- BrasilAPI: CEP, CNPJ, bancos, feriados em uma API gratuita
- Focus NFe / NF-e.io: emissão de nota fiscal
Exemplos de Prompts
Use api-builder para criar documentação OpenAPI 3.0 da minha API de [domínio].
Endpoints que preciso documentar: [lista].
Autenticação: [JWT/API Key/OAuth].
Crie spec completo com exemplos de request/response e todos os erros possíveis.
Regras
- Nunca usar verbos em URLs REST — recursos são substantivos
- Versionamento na URL: /v1/ — nunca por header em APIs públicas
- Paginação sempre: cursor-based para grandes datasets, offset para simples
- Rate limiting: documentar limites no header X-RateLimit-*
- HTTPS obrigatório: nunca aceitar HTTP em produção
