Princípios de Design de API

Domine os princípios de design de API REST e GraphQL para construir APIs intuitivas, escaláveis e fáceis de manter que agradem aos desenvolvedores e resistam ao teste do tempo.

Quando Usar Esta Habilidade

• Projetando novas APIs REST ou GraphQL
• Refatorando APIs existentes para melhor usabilidade
• Estabelecendo padrões de design de API para sua equipe
• Revisando especificações de API antes da implementação
• Migrando entre paradigmas de API (REST para GraphQL, etc.)
• Criando documentação de API amigável para desenvolvedores
• Otimizando APIs para casos de uso específicos (mobile, integrações de terceiros)

Conceitos Principais

1. Princípios de Design RESTful

Arquitetura Orientada a Recursos

• Recursos são substantivos (usuários, pedidos, produtos), não verbos
• Use métodos HTTP para ações (GET, POST, PUT, PATCH, DELETE)
• URLs representam hierarquias de recursos
• Convenções de nomenclatura consistentes

Semântica dos Métodos HTTP:

• GET: Recuperar recursos (idempotente, seguro)
• POST: Criar novos recursos
• PUT: Substituir recurso inteiro (idempotente)
• PATCH: Atualizações parciais de recursos
• DELETE: Remover recursos (idempotente)

2. Princípios de Design GraphQL

Desenvolvimento Orientado a Schema (Schema-First)

• Tipos definem seu modelo de domínio
• Queries para leitura de dados
• Mutations para modificação de dados
• Subscriptions para atualizações em tempo real

Estrutura de Query:

• Clientes solicitam exatamente o que precisam
• Ponto de extremidade único, múltiplas operações
• Schema fortemente tipado
• Introspecção integrada

3. Estratégias de Versionamento de API

Versionamento de URL:

/api/v1/users
/api/v2/users

Versionamento de Cabeçalho:

Accept: application/vnd.api+json; version=1

Versionamento de Parâmetro de Query:

/api/users?version=1

Padrões Detalhados e Exemplos Práticos

A documentação detalhada de padrões está em references/details.md. Leia este arquivo quando o nível de navegação acima for insuficiente.

Melhores Práticas

APIs REST

1. Nomenclatura Consistente: Use substantivos no plural para coleções (/users, não /user)
2. Stateless (Sem Estado): Cada solicitação contém todas as informações necessárias
3. Use Códigos de Status HTTP Corretamente: 2xx sucesso, 4xx erros do cliente, 5xx erros do servidor
4. Versionamento da API: Planeje alterações que quebram a compatibilidade desde o primeiro dia
5. Paginação: Sempre pague coleções grandes
6. Rate Limiting (Limitação de Taxa): Proteja sua API com limites de taxa
7. Documentação: Use OpenAPI/Swagger para documentação interativa

APIs GraphQL

1. Schema First: Projete o schema antes de escrever os resolvers
2. Evite N+1: Use DataLoaders para busca eficiente de dados
3. Validação de Entrada: Valide nos níveis de schema e resolver
4. Tratamento de Erros: Retorne erros estruturados em payloads de mutation
5. Paginação: Use paginação baseada em cursor (especificação Relay)
6. Depreciação: Use a diretiva @deprecated para migração gradual
7. Monitoramento: Monitore a complexidade da query e o tempo de execução

Armadilhas Comuns

• Over-fetching/Under-fetching (REST): Resolvido em GraphQL, mas requer DataLoaders
• Alterações que Quebram a Compatibilidade: Versionar APIs ou usar estratégias de depreciação
• Formatos de Erro Inconsistentes: Padronize as respostas de erro
• Falta de Rate Limiting: APIs sem limites são vulneráveis a abusos
• Documentação Ruim: APIs não documentadas frustram os desenvolvedores
• Ignorar Semântica HTTP: Usar POST para operações idempotentes quebra as expectativas
• Acoplamento Forte: A estrutura da API não deve espelhar o esquema do banco de dados