Convenções de URL, métodos e erros: API previsível e normalizado

Última edição:

Diana Romanova

—

Junho 25, 2025

Convenções de URL, métodos, erros ('GET', 'POST', 'PUT',' DELETE ')

Uma API confiável e compreensível começa com regras claras para a construção de interfaces. Adotamos as melhores práticas do REST para que cada desenvolvedor saiba o que esperar: a estrutura do URL é lógica, os métodos correspondem à ação e os erros são facilmente interpretados.

Isso reduz o limite de entrada, simplifica a integração e permite que o sistema seja escalado sem caos.

Convenções de URL e métodos HTTP

Método	Destino	Exemplo de consulta
`GET`	Receber recurso	`GET /users/42`
`POST`	Criar um novo recurso	`POST /users`
`PUT`	Atualização completa do recurso	`PUT /users/42`
`PATCH`	Atualização parcial do recurso (opz) `PATCH /users/42`
`DELETE`	Remover recurso	`DELETE /users/42`

São usados substantivos múltiplos ('/users ', '/devices', '/games ')

As entidades aninhadas são descritas como hierarquias ('/users/42/sessions ')
Todas as solicitações são feitas através do HTTPS

Padrões de processamento de erros

Código	Valor	Exemplo de mensagem
`400`	Pedido inválido	`Missing required field: email`
`401`	Não autorizado	`Invalid token or expired session`
`403`	Acesso proibido	`Access denied to resource`
`404`	Não foi encontrado	`User with ID 42 not found`
`409`	Conflito (por exemplo, duplicação)	`Email already in use`
`422`	Erro de validação	`Field 'age' must be a number`
`500`	Erro interno do servidor	`Unexpected exception, contact support`

Estrutura de resposta ao erro:

json
{
"error": {
"code": 400,   "message": "Missing required field: email",   "details": {...}
}
}

Vantagens para desenvolvedores

Compreender rapidamente a lógica da API sem excesso de documentação

Abordagem unificada de todos os módulos e entidades
Depuração e logagem fácil através de códigos e formatos padrão
Compatibilidade com OpenAPI/Swagger, Postman, SDK
Simplificar suporte, testes e CI/CD

Onde é particularmente importante

Plataformas com API aberta ou parceira

Projetos com vários comandos de desenvolvimento
Arquitetura de microsserviços ou abordagem API-first
Sistemas com mais entidades e interações

Convenções unificadas tornam a API confiável, compreensível e conveniente. Adotamos as melhores práticas de REST para que cada integração ocorra rapidamente, sem equívocos e com a máxima previsibilidade.