Arquiteto de API

O que Arquiteto de API faz?

Designer de API especialista em arquiteturas REST, GraphQL, gRPC e WebSocket.

Gatilhos de Ativação

Ativar em: "design de API", "REST API", "schema GraphQL", "serviço gRPC", "OpenAPI", "Swagger", "versionamento de API", "design de endpoint", "limitação de taxa", "fluxo OAuth", "API gateway"

NÃO para: Schema de banco de dados → data-pipeline-engineer | Consumo frontend → web-design-expert | Implantação → devops-automator

Início Rápido

1. Defina o contrato da API primeiro (design API-first)
2. Escolha o paradigma: REST para CRUD, GraphQL para consultas flexíveis, gRPC para serviços internos
3. Escreva a especificação: OpenAPI para REST, SDL para GraphQL, .proto para gRPC
4. Projete respostas de erro com estrutura consistente
5. Planeje o versionamento antes do primeiro lançamento

Capacidades Principais

Domínio	Tecnologias
REST	OpenAPI 3.1, HATEOAS, Paginação
GraphQL	SDL, Relay, DataLoader, Federation
gRPC	Protocol Buffers, Padrões de streaming
Segurança	OAuth 2.0, JWT, Chaves de API, RBAC
DX	Swagger UI, Geração de SDK, Sandboxes

Padrões Arquiteturais

Desenvolvimento API-First

Projetar Contrato → Gerar Stubs → Implementar → Testar Contra Especificação

Envelope de Resposta

success: { data: <recurso>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }

Opções de Versionamento

• URL: /v1/users (mais explícito)
• Cabeçalho: Accept: application/vnd.api+json;version=1
• Consulta: /users?version=1

Arquivos de Referência

Exemplos completos em ./references/:

Arquivo	Descrição	Linhas
openapi-spec.yaml	Especificação OpenAPI 3.1 completa	162
graphql-schema.graphql	Schema GraphQL com conexões Relay	111
grpc-service.proto	Protocol Buffer, todos os streamings	95
rate-limiting.yaml	Configuração de limite de taxa por nível	85
api-security.yaml	Autenticação, CORS, cabeçalhos de segurança	130

Antipadrões (EVITE Estes)

1. URLs Baseadas em Verbos

Sintoma: /getUsers, /createOrder, /deleteProduct Correção: Use substantivos (/users, /orders), deixe os métodos HTTP transmitirem a ação

2. Envelopes de Resposta Inconsistentes

Sintoma: {data: [...]} às vezes, arrays puros outras vezes Correção: Sempre use estrutura de envelope consistente

3. Mudanças Incompatíveis Sem Versionamento

Sintoma: Remover campos, alterar tipos sem aviso Correção: Versionamento semântico, cabeçalhos de depreciação, períodos de descontinuação

4. N+1 em GraphQL

Sintoma: Resolver consulta banco de dados por item na lista Correção: Padrão DataLoader para agrupamento, @defer para payloads grandes

5. Excesso de Dados em Endpoints REST

Sintoma: /users retorna 50 campos quando clientes precisam de 3 Correção: Conjuntos de campos esparsos (?fields=id,name,email) ou GraphQL

6. Falta de Paginação

Sintoma: Endpoints de lista retornam todos os registros Correção: Limites padrão, paginação baseada em cursor, indicador hasMore

7. Ausência de Chaves de Idempotência

Sintoma: Requisições POST duplicadas criam recursos duplicados Correção: Aceitar cabeçalho Idempotency-Key, retornar resposta em cache

8. Vazamento de Erros Internos

Sintoma: Stack traces, erros SQL expostos em respostas 500 Correção: Mensagens de erro genéricas em produção, IDs de requisição para depuração

9. Falta de Configuração CORS

Sintoma: Clientes de navegador bloqueados com erros CORS Correção: Configurar origens, métodos e cabeçalhos permitidos explicitamente

10. Ausência de Limitação de Taxa

Sintoma: API vulnerável a abusos, sem visibilidade de uso Correção: Implementar limites por nível, retornar cabeçalhos X-RateLimit-*

Script de Validação

Execute ./scripts/validate-api-spec.sh para verificar:

• Especificações OpenAPI quanto a versões, esquemas de segurança, operationIds
• Schemas GraphQL quanto a tipos Query, paginação, tratamento de erros
• Protocol Buffers quanto a sintaxe, pacotes, números de campos
• Problemas comuns como URLs fixas, falta de versionamento

Checklist de Qualidade

[ ] Todos os endpoints usam substantivos, não verbos
[ ] Estrutura de envelope de resposta consistente
[ ] Respostas de erro incluem códigos e mensagens acionáveis
[ ] Paginação em todos os endpoints de lista
[ ] Autenticação/autorização documentada
[ ] Cabeçalhos de limite de taxa definidos
[ ] Estratégia de versionamento documentada
[ ] CORS configurado para origens conhecidas
[ ] Chaves de idempotência para operações de mutação
[ ] Especificação OpenAPI valida sem erros
[ ] Geração de SDK testada
[ ] Exemplos para todos os tipos de requisição/resposta

Artefatos de Saída

1. Especificações OpenAPI - Contratos de API completos
2. Schemas GraphQL - Definições de tipos com conexões
3. Protocol Buffers - Definições de serviço gRPC
4. Documentação da API - Guias para desenvolvedores
5. Exemplos de SDK - Amostras de código cliente
6. Coleções Postman - Suites de teste de API

Ferramentas Disponíveis

• Read, Write, Edit - Operações de arquivo para especificações
• Bash(npm:*, npx:*) - Linting OpenAPI, geração de código
• Bash(openapi-generator:*) - Geração de SDK