Aplicativos, sites, ERPs e integrações com parceiros conversam por APIs. Quando uma API é bem projetada, novos clientes se integram em horas. Quando é mal projetada, cada integração vira um projeto cheio de exceções. Por isso, seguir as boas práticas de API REST é um investimento que se paga rapidamente.
Neste artigo, reunimos as convenções mais importantes, com exemplos práticos.
O que é uma API REST
REST, ou Representational State Transfer, é um estilo de arquitetura definido por Roy Fielding em 2000. Uma API REST expõe recursos, como clientes, pedidos e produtos, por meio de URLs. Em seguida, usa os verbos do protocolo HTTP para operar sobre eles. Na maioria dos casos, os dados trafegam em JSON.
1. Use substantivos no plural para os recursos
A URL identifica o recurso. A ação fica por conta do verbo HTTP. Veja a diferença:
- Evite:
/getClientes,/criarPedido - Prefira:
/clientes,/pedidos,/pedidos/42/itens
2. Use os verbos HTTP corretamente
- GET: consulta dados, sem alterar nada.
- POST: cria um novo recurso.
- PUT: substitui um recurso inteiro.
- PATCH: atualiza apenas alguns campos.
- DELETE: remove um recurso.
Além disso, GET, PUT e DELETE devem ser idempotentes. Ou seja, repetir a mesma requisição produz o mesmo resultado.
3. Retorne os códigos de status adequados
- 200 OK para sucesso e 201 Created após criar um recurso.
- 204 No Content quando não há corpo na resposta.
- 400 Bad Request e 422 Unprocessable Entity para dados inválidos.
- 401 Unauthorized sem autenticação e 403 Forbidden sem permissão.
- 404 Not Found quando o recurso não existe.
- 429 Too Many Requests ao exceder o limite de chamadas.
- 500 apenas para erros inesperados do servidor.
Retornar 200 com uma mensagem de erro no corpo confunde clientes e ferramentas de monitoramento.
4. Padronize as mensagens de erro
Todas as respostas de erro devem ter o mesmo formato, com código, mensagem legível e detalhes por campo. A especificação RFC 9457, conhecida como Problem Details, é uma boa referência.
5. Versione desde o primeiro dia
Mudanças incompatíveis vão acontecer. Para não quebrar integrações existentes, inclua a versão na URL, como /v1/pedidos, ou em um cabeçalho. Assim, você publica a v2 sem afetar quem ainda usa a versão anterior.
6. Pagine, filtre e ordene listas
Nunca retorne todos os registros de uma vez. Use parâmetros como ?page=2&per_page=50, filtros como ?status=pago e ordenação como ?sort=-created_at. Em grandes volumes, a paginação por cursor é mais eficiente do que a paginação por número de página.
7. Proteja a API
- Use sempre HTTPS.
- Autentique com tokens, como OAuth 2.0 ou tokens de acesso com expiração.
- Verifique a permissão em cada recurso para evitar falhas do tipo IDOR, em que um usuário acessa dados de outro apenas trocando o ID.
- Aplique limite de requisições por cliente.
- Valide toda entrada e nunca exponha detalhes internos em mensagens de erro.
8. Documente com OpenAPI
Uma API sem documentação é uma API difícil de usar. A especificação OpenAPI permite gerar documentação interativa, exemplos e até clientes automaticamente. Inclua exemplos reais de requisição e resposta para cada endpoint.
Perguntas frequentes
REST ou GraphQL?
REST é simples, aproveita o cache HTTP e atende a maioria dos casos. GraphQL é útil quando muitos clientes diferentes precisam de combinações variadas de dados.
Qual a diferença entre PUT e PATCH?
O PUT substitui o recurso inteiro. O PATCH altera apenas os campos enviados.
Conclusão
Uma boa API REST é previsível: recursos bem nomeados, verbos corretos, status coerentes, versionamento e documentação clara. Essas práticas reduzem o tempo de integração e evitam falhas de segurança. Se a sua empresa precisa desenvolver ou integrar APIs, conte com a WDS Developer.
