API que escala sem padrão vira zona. Já vi projeto que começou com dois endpoints e, em seis meses, tinha 47 rotas, cada uma com um jeito diferente de devolver erro. Se você está aqui, provavelmente já sentiu essa dor. A boa notícia: existem padrões de design que evitam que sua API vire um legado antes do tempo. Abaixo, 7 padrões que uso e recomendo para APIs RESTful que precisam crescer sem surtos.
1. Versionamento semântico na URL
Nada de versionar por header ou query string. Colocar a versão na URL (/v1/, /v2/) é o padrão mais explícito e fácil de depurar. Quando você quebra compatibilidade, sobe uma nova versão e mantém a anterior por um período. O cliente sabe exatamente o que está chamando. Exemplo prático: a API do GitHub usa /v3/ há anos sem confusão.
2. Paginação com cursor, não com page number
Page-based pagination quebra quando registros são inseridos ou removidos entre requisições, o usuário pula ou repete dados. Paginação com cursor (um token opaco que aponta para o próximo item) resolve isso. APIs como a do Stripe usam cursor e funcionam bem com milhões de registros.
3. Rate limiting com tokens (Token Bucket)
Rate limiting evita que um cliente abusivo derrube sua API. O padrão Token Bucket é simples: cada cliente tem um saldo de tokens que se renova a cada intervalo. Quando acaba, recebe 429 Too Many Requests. Inclua headers como X-RateLimit-Remaining para o cliente se autorregular.
4. HATEOAS para navegação natural
HATEOAS (Hypermedia as the Engine of Application State) faz sua API se auto-documentar. Cada resposta inclui links relacionados (rel": "self", rel": "next", rel": "orders"). O cliente descobre os próximos passos sem precisar de documentação externa. Na prática, reduz acoplamento e facilita evolução.
5. Tratamento consistente de erros
Erro precisa ter estrutura fixa: um código interno, uma mensagem legível e, se possível, um link para documentação. Padrão comum: { "error": { "code": "INVALID_PARAM", "message": "O campo 'email' é obrigatório", "details": [...] } }. Isso evita que cada endpoint invente um formato diferente.
6. Cache com ETags e If-None-Match
ETags (hash do recurso) permitem que o cliente faça requisições condicionais. Se o recurso não mudou, o servidor devolve 304 Not Modified sem corpo. Reduz latência e carga no servidor. APIs RESTful maduras, como a do Twitter, usam ETags para economizar banda.
7. Idempotência em endpoints POST
POST não é idempotente por padrão, mas em operações críticas (como pagamento), você pode torná-lo idempotente com uma chave de idempotência enviada no header. Se o cliente repetir a requisição com a mesma chave, o servidor devolve o mesmo resultado sem processar de novo. Stripe usa isso e evita cobranças duplicadas.
Qual padrão escolher primeiro?
Se sua API está começando, priorize versionamento e tratamento de erros, são baratos de implementar e evitam retrabalho. Conforme cresce, adicione rate limiting e paginação com cursor. Cache e idempotência entram quando a latência ou a confiabilidade se tornam críticas. Nenhum padrão salva tudo sozinho, mas juntos eles formam uma base sólida.
FAQ
O que são padrões de design para API?
São soluções reutilizáveis para problemas comuns no desenvolvimento de APIs, como versionamento, paginação e tratamento de erros. Eles padronizam a arquitetura e facilitam a manutenção.
Qual a diferença entre REST e RESTful?
REST é um conjunto de princípios arquiteturais. RESTful é a implementação prática desses princípios em uma API. Uma API RESTful segue as restrições REST, como stateless e uso de métodos HTTP.
Como versionar uma API sem quebrar clientes?
Use versionamento na URL (/v1/, /v2/). Mantenha versões antigas ativas por um período e comunique a depreciação com headers como Sunset e Deprecation.
Paginação com cursor é melhor que com offset?
Sim, em APIs que crescem rápido. Cursor evita problemas de consistência quando dados são inseridos ou removidos durante a navegação, garantindo que cada página seja estável.
O que é rate limiting e por que usar?
Rate limiting controla quantas requisições um cliente pode fazer em um intervalo. Evita abusos e protege o servidor. O padrão Token Bucket é simples e eficaz.
HATEOAS é obrigatório em APIs RESTful?
Não, mas é uma recomendação forte de Roy Fielding, criador do REST. Na prática, reduz acoplamento entre cliente e servidor, mas aumenta a complexidade inicial.