| name | api-design-reviewer |
| description | Revisão e análise completa de designs de API com foco em convenções REST, melhores práticas e padrões da indústria. Fornece linting automatizado, detecção de mudanças disruptivas e scorecards de design. |
| agents | ["claude-code"] |
API Design Reviewer
Nível: POWERFUL
Categoria: Engineering / Architecture
Visão Geral
A skill API Design Reviewer fornece análise e revisão abrangente de designs de API, focando em convenções REST, melhores práticas e padrões da indústria. Esta skill ajuda equipes de engenharia a construir APIs consistentes, manuteníveis e bem projetadas por meio de linting automatizado, detecção de mudanças disruptivas e scorecards de design.
Capacidades Principais
1. Linting de API e Análise de Convenções
- Convenções de Nomenclatura de Recursos: Aplica kebab-case para recursos, camelCase para campos
- Uso de Métodos HTTP: Valida uso adequado de GET, POST, PUT, PATCH, DELETE
- Estrutura de URL: Analisa padrões de endpoint para consistência e design RESTful
- Conformidade de Status Code: Garante uso de códigos de status HTTP apropriados
- Formatos de Resposta de Erro: Valida estruturas de resposta de erro consistentes
- Cobertura de Documentação: Verifica descrições ausentes e lacunas na documentação
2. Detecção de Mudanças Disruptivas
- Remoção de Endpoints: Detecta endpoints removidos ou depreciados
- Mudanças no Shape de Resposta: Identifica modificações nas estruturas de resposta
- Remoção de Campos: Rastreia campos removidos ou renomeados nas respostas da API
- Mudanças de Tipo: Detecta modificações de tipo de campo que podem quebrar clientes
- Adições de Campos Obrigatórios: Sinaliza novos campos obrigatórios que podem quebrar integrações existentes
- Mudanças de Status Code: Detecta mudanças nos status codes esperados
3. Pontuação e Avaliação de Design de API
- Análise de Consistência (30%): Avalia convenções de nomenclatura, padrões de resposta e consistência estrutural
- Qualidade da Documentação (20%): Avalia completude e clareza da documentação da API
- Implementação de Segurança (20%): Revisa autenticação, autorização e cabeçalhos de segurança
- Design de Usabilidade (15%): Analisa facilidade de uso, descoberta e experiência do desenvolvedor
- Padrões de Desempenho (15%): Avalia cache, paginação e padrões de eficiência
Princípios de Design REST
Convenções de Nomenclatura de Recursos
✅ Bons Exemplos:
- /api/v1/users
- /api/v1/user-profiles
- /api/v1/orders/123/line-items
❌ Maus Exemplos:
- /api/v1/getUsers
- /api/v1/user_profiles
- /api/v1/orders/123/lineItems
Uso de Métodos HTTP
- GET: Recuperar recursos (seguro, idempotente)
- POST: Criar novos recursos (não idempotente)
- PUT: Substituir recursos inteiros (idempotente)
- PATCH: Atualizações parciais de recursos (não necessariamente idempotente)
- DELETE: Remover recursos (idempotente)
Melhores Práticas de Estrutura de URL
Recursos de Coleção: /api/v1/users
Recursos Individuais: /api/v1/users/123
Recursos Aninhados: /api/v1/users/123/orders
Ações: /api/v1/users/123/activate (POST)
Filtragem: /api/v1/users?status=active&role=admin
Estratégias de Versionamento
1. Versionamento por URL (Recomendado)
/api/v1/users
/api/v2/users
Vantagens: Claro, explícito, fácil de rotear
Desvantagens: Proliferação de URLs, complexidade de cache
2. Versionamento por Header
GET /api/users
Accept: application/vnd.api+json;version=1
Vantagens: URLs limpas, negociação de conteúdo
Desvantagens: Menos visível, mais difícil de testar manualmente
3. Versionamento por Media Type
GET /api/users
Accept: application/vnd.myapi.v1+json
Vantagens: RESTful, suporta múltiplas representações
Desvantagens: Complexo, mais difícil de implementar
4. Versionamento por Parâmetro de Query
/api/users?version=1
Vantagens: Simples de implementar
Desvantagens: Não é RESTful, pode ser ignorado
Padrões de Paginação
Paginação Baseada em Offset
{
"data": [...],
"pagination": {
"offset": 20,
"limit": 10,
"total": 150,
"hasMore": true
}
}
Paginação Baseada em Cursor
{
"data": [...],
"pagination": {
"nextCursor": "eyJpZCI6MTIzfQ==",
"hasMore": true
}
}
Paginação Baseada em Página
{
"data": [...],
"pagination": {
"page": 3,
"pageSize": 10,
"totalPages": 15,
"totalItems": 150
}
}
Formatos de Resposta de Erro
Estrutura de Erro Padrão
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request contains invalid parameters",
"details": [
{
"field": "email",
"code": "INVALID_FORMAT",
"message": "Email address is not valid"
}
],
"requestId": "req-123456",
"timestamp": "2024-02-16T13:00:00Z"
}
}
Uso de Códigos de Status HTTP
- 400 Bad Request: Sintaxe de requisição ou parâmetros inválidos
- 401 Unauthorized: Autenticação necessária
- 403 Forbidden: Acesso negado (autenticado, mas não autorizado)
- 404 Not Found: Recurso não encontrado
- 409 Conflict: Conflito de recurso (duplicata, incompatibilidade de versão)
- 422 Unprocessable Entity: Sintaxe válida, mas erros semânticos
- 429 Too Many Requests: Limite de taxa excedido
- 500 Internal Server Error: Erro inesperado do servidor
Padrões de Autenticação e Autorização
Autenticação por Bearer Token
Authorization: Bearer <token>
Autenticação por API Key
X-API-Key: <api-key>
Authorization: Api-Key <api-key>
Fluxo OAuth 2.0
Authorization: Bearer <oauth-access-token>
Controle de Acesso Baseado em Papel (RBAC)
{
"user": {
"id": "123",
"roles": ["admin", "editor"],
"permissions": ["read:users", "write:orders"]
}
}
Implementação de Rate Limiting
Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
Resposta ao Exceder o Limite
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"retryAfter": 3600
}
}
HATEOAS (Hypermedia as the Engine of Application State)
Exemplo de Implementação
{
"id": "123",
"name": "John Doe",
"email": "john@example.com",
"_links": {
"self": { "href": "/api/v1/users/123" },
"orders": { "href": "/api/v1/users/123/orders" },
"profile": { "href": "/api/v1/users/123/profile" },
"deactivate": {
"href": "/api/v1/users/123/deactivate",
"method": "POST"
}
}
}
Idempotência
Métodos Idempotentes
- GET: Sempre seguro e idempotente
- PUT: Deve ser idempotente (substituir recurso inteiro)
- DELETE: Deve ser idempotente (mesmo resultado)
- PATCH: Pode ou não ser idempotente
Chaves de Idempotência
POST /api/v1/payments
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Diretrizes de Compatibilidade Retroativa
Mudanças Seguras (Não Disruptivas)
- Adicionar campos opcionais às requisições
- Adicionar campos às respostas
- Adicionar novos endpoints
- Tornar campos obrigatórios opcionais
- Adicionar novos valores de enum (com tratamento gracioso)
Mudanças Disruptivas (Requerem Bump de Versão)
- Remover campos das respostas
- Tornar campos opcionais obrigatórios
- Alterar tipos de campos
- Remover endpoints
- Alterar estruturas de URL
- Modificar formatos de resposta de erro
Validação OpenAPI/Swagger
Componentes Obrigatórios
- Informações da API: Título, descrição, versão
- Informações do Servidor: URLs base e descrições
- Definições de Path: Todos os endpoints com métodos
- Definições de Parâmetro: Parâmetros de query, path e header
- Schemas de Request/Response: Modelos de dados completos
- Definições de Segurança: Esquemas de autenticação
- Respostas de Erro: Formatos de erro padrão
Melhores Práticas
- Usar convenções de nomenclatura consistentes
- Fornecer descrições detalhadas para todos os componentes
- Incluir exemplos para objetos complexos
- Definir componentes e schemas reutilizáveis
- Validar contra a especificação OpenAPI
Considerações de Desempenho
Estratégias de Cache
Cache-Control: public, max-age=3600
ETag: "123456789"
Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT
Transferência Eficiente de Dados
- Usar métodos HTTP apropriados
- Implementar seleção de campos (
?fields=id,name,email)
- Suportar compressão (gzip)
- Implementar paginação eficiente
- Usar ETags para requisições condicionais
Otimização de Recursos
- Evitar consultas N+1
- Implementar operações em lote
- Usar processamento assíncrono para operações pesadas
- Suportar atualizações parciais (PATCH)
Melhores Práticas de Segurança
Validação de Entrada
- Validar todos os parâmetros de entrada
- Sanitizar dados do usuário
- Usar consultas parametrizadas
- Implementar limites de tamanho de requisição
Segurança de Autenticação
- Usar HTTPS em todo lugar
- Implementar armazenamento seguro de tokens
- Suportar expiração e refresh de tokens
- Usar mecanismos de autenticação fortes
Controles de Autorização
- Implementar princípio do menor privilégio
- Usar permissões baseadas em recursos
- Suportar controle de acesso granular
- Auditar padrões de acesso
Ferramentas e Scripts
api_linter.py
Analisa especificações de API para conformidade com convenções REST e melhores práticas.
Funcionalidades:
- Validação de spec OpenAPI/Swagger
- Verificações de convenção de nomenclatura
- Validação de uso de método HTTP
- Consistência de formato de erro
- Análise de completude da documentação
breaking_change_detector.py
Compara versões de especificação de API para identificar mudanças disruptivas.
Funcionalidades:
- Comparação de endpoints
- Detecção de mudanças de schema
- Rastreamento de remoção/modificação de campos
- Geração de guia de migração
- Avaliação de severidade de impacto
api_scorecard.py
Fornece pontuação abrangente da qualidade do design de API.
Funcionalidades:
- Pontuação multidimensional
- Recomendações detalhadas de melhoria
- Avaliação por nota (A-F)
- Comparações de desempenho
- Rastreamento de progresso
Exemplos de Integração
Integração CI/CD
- name: "api-linting"
run: python scripts/api_linter.py openapi.json
- name: "breaking-change-detection"
run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json
- name: "api-scorecard"
run: python scripts/api_scorecard.py openapi.json
Pre-commit Hooks
#!/bin/bash
python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json
if [ $? -ne 0 ]; then
echo "API linting failed. Please fix the issues before committing."
exit 1
fi
Resumo de Melhores Práticas
- Consistência Primeiro: Manter nomenclatura, formatos de resposta e padrões consistentes
- Documentação: Fornecer documentação de API abrangente e atualizada
- Versionamento: Planejar a evolução com estratégias claras de versionamento
- Tratamento de Erros: Implementar respostas de erro consistentes e informativas
- Segurança: Construir segurança em cada camada da API
- Desempenho: Projetar para escala e eficiência desde o início
- Compatibilidade Retroativa: Minimizar mudanças disruptivas e fornecer caminhos de migração
- Testes: Implementar testes abrangentes incluindo testes de contrato
- Monitoramento: Adicionar observabilidade para uso e desempenho da API
- Experiência do Desenvolvedor: Priorizar facilidade de uso e documentação clara
Anti-Padrões a Evitar
- URLs Baseadas em Verbos: Use substantivos para recursos, não ações
- Formatos de Resposta Inconsistentes: Manter estruturas de resposta padrão
- Aninhamento Excessivo: Evitar hierarquias de recursos profundamente aninhadas
- Ignorar Status Codes HTTP: Usar status codes apropriados para diferentes cenários
- Mensagens de Erro Ruins: Fornecer informações de erro específicas e acionáveis
- Paginação Ausente: Sempre paginar endpoints de lista
- Sem Estratégia de Versionamento: Planejar a evolução da API desde o primeiro dia
- Expor Estrutura Interna: Projetar APIs para consumo externo, não conveniência interna
- Rate Limiting Ausente: Proteger sua API contra abuso e sobrecarga
- Testes Inadequados: Testar todos os aspectos incluindo casos de erro e condições extremas
Conclusão
A skill API Design Reviewer fornece um framework abrangente para construir, revisar e manter APIs REST de alta qualidade. Seguindo estas diretrizes e usando as ferramentas fornecidas, equipes de desenvolvimento podem criar APIs consistentes, bem documentadas, seguras e manuteníveis.
O uso regular das ferramentas de linting, detecção de mudanças disruptivas e pontuação garante melhoria contínua e ajuda a manter a qualidade da API ao longo do ciclo de vida de desenvolvimento.
