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 negado | `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.