APIs REST são o coração da arquitetura de software moderna, permitindo comunicação fluida entre sistemas. Essa imagem elaborado por Nina Fernanda Durán ilustra muito bem esses princípios. Construir APIs robustas e confiáveis exige atenção aos detalhes. Vamos explorar as práticas essenciais:
- Códigos de Status HTTP
Comunique o status da resposta com clareza, existe um padrão de retornos que a API deve seguir para trazer clareza sobre o que aconteceu com o processamento da requisição.
• 1xx Informativo: Processamentos em geral
• 2xx Sucesso: Resposta sinalizando que o processamento foi bem sucedido ou acontecerá de forma assincrona.
• 3xx Redirecionamento: Ação adicional necessária
• 4xx Erros do Cliente: Há algo de errado na requisição, seja um token expirado ou até mesmo um atributo invalido.
• 5xx Erros do Servidor: o famoso Internal Server Error
Boa prática: Evite criar APIs que não sigam esse padrão. Vai por mim, muita gente já ficou horas tentando entender o porque uma API deu erro mas retornou 200 – OK ¯\_( ͡• ͜ʖ ͡•)_/¯
2. Query parameters
Use parâmetros de query de forma eficaz para melhorar a performance, usabilidade e padronização.
• Paginação: Gerencie grandes volumes de dados com /usuarios?page=1&size=10.
• Filtragem: Permita buscas específicas, como /usuarios?nome=gustavo.
• Ordenação: Retorne resultados ordenados com /usuarios?sort=nome.
Lembrando que esses sao só exemplos, nada impede de criar seus proprios parametros 😀
Os filtros sort, page e size são um padrão que geralmente é utilizado e não se costuma traduzi-los.
Combinar esses elementos aprimora a versatilidade e eficiência da API.
3. Autenticação
Proteja seus Endpoints
Use métodos seguros para autenticar usuários:
• OAuth2: O padrão da indústria para autenticação baseada em token.
• Tokens JWT: Autenticação escalável e stateless, adequada para sistemas distribuídos.
Boa prática: Use HTTPS para criptografar todas as requisições.
4. Versionamento
APIs evoluem, mas clientes antigos não devem quebrar. Implemente versionamento através de:
• Baseado em caminho: /v1/usuarios.
• Baseado em header: Inclua ‘X-API-Version: 1’ nas requisições.
Em uma organização de grande porte, onde a modernização é constante e APIs evoluem a cada três meses, o versionamento é essencial. Ele garante que a versão 1.0 de uma API continue funcionando para os times integrados, mesmo após o lançamento da versão 2.0. Isso reduz o impacto das mudanças, permitindo que as equipes adaptem suas integrações no tempo necessário, sem interrupções nos serviços.
5. Métodos HTTP
Defina ações claras para Recursos, APIs REST dependem de métodos HTTP específicos para consistência:
• GET: Buscar dados.
• POST: Criar um novo recurso.
• PUT: Atualizar/substituir um recurso.
• PATCH: Modificar partes especificas de um recurso.
• DELETE: Remover um recurso.
Boa prática: Como o próprio metodo da requisição já deixa implicita a sua ação, evite colocar a ação na rota, como por exemplo:
GET – /consultar-usuarios/{id} ou POST – /salvar-pedido
6. Idempotencia
Torne sua API previsivel, certifique-se de que solicitações repetidas produzam o mesmo resultado (ex.: PUT, DELETE). Isso é crucial para confiabilidade em retries.
Por que isso é necessário?: A idempotência é essencial para mecanismos de retry, especialmente em sistemas distribuídos. Um caso comum de idempotência em HTTP POST, por exemplo, é no processamento de pagamentos. Para evitar cobranças duplicadas, cada requisição inclui um idempotency key único (“transaction-12345”). Se a mesma requisição for enviada novamente com o mesmo header, o servidor verifica o identificador e retorna o resultado original, em vez de processar o pagamento novamente. Isso garante segurança e evita duplicidades, mesmo com falhas de rede ou cliques repetidos.
7. Padrões de semantica
Use estruturas intuitivas e de facil entendimento tanto para o time de tecnologia como demais times.
/v1/auth/login: Para autenticação.
/v1/usuarios/{id}: Buscar detalhes específicos do usuário.
Por que importa: Paths intuitivos simplificam o aprendizado e tornam a API mais clara.
8. Domain Model-Driven Design
Reflita entidades do mundo real para novamente facilitar o entendimento de todos.
GET /produtos/{id}: Acesse um produto específico.
GET /produtos/{id}/avaliacoes: Recupera todas as avaliações de um produto especifico.
POST /produtos/{id}/avaliacoes: Salva uma nova avaliação em um produto especifico
