Retorno de validações semânticas em API Rest
Published: 2024-03-26 19:36:47


Em um mundo cada vez mais conectado, as APIs desempenham um papel crucial na troca de informações entre sistemas e na construção de aplicativos robustos e interconectados. No entanto, à medida que a complexidade das aplicações e das interações entre sistemas aumenta, surgem desafios relacionados à integridade e à consistência dos dados transmitidos por meio dessas interfaces.

Um aspecto fundamental para garantir a qualidade e a confiabilidade das APIs é a capacidade de lidar com erros semânticos nos dados fornecidos pelas requisições. Estes erros, muitas vezes negligenciados, podem comprometer a integridade dos dados e afetar a funcionalidade geral do sistema. Neste artigo, exploraremos o que são os erros semânticos dos dados em APIs, como eles podem surgir e como podem ser mitigados.

O que são erros semânticos?

Erros semânticos nos dados fornecidos referem-se a problemas relacionados ao significado ou à interpretação dos dados enviados em uma requisição para a API. Enquanto erros de sintaxe são detectados facilmente através de verificações formais, erros semânticos exigem uma compreensão mais profunda do contexto e das regras de negócio envolvidas.

Exemplos de erros semânticos:

- Em uma API de gerenciamento de usuários, tentar cadastrar um usuário com um endereço de e-mail já existente no sistema.
- Em uma API de reservas de hotel, tentar fazer uma reserva para uma data que já passou.
- Em uma API de e-commerce, tentar adicionar um produto ao carrinho com uma quantidade maior do que a disponível em estoque.

Detectando e tratando erros semânticos:

A detecção de erros semânticos nos dados fornecidos é essencial para garantir a integridade e a consistência dos sistemas. Isso geralmente é feito por meio de validações em código implementadas na API, que verificam se os dados fornecidos estão em conformidade com as regras de negócio estabelecidas.

Quando um erro semântico é detectado, a API deve retornar uma resposta adequada, geralmente utilizando códigos de status HTTP como o 422 "Unprocessable Entity". Além disso, é importante fornecer informações claras sobre o erro ocorrido, para que o cliente possa corrigir os dados e reenviar a requisição.

Na imagem abaixo, podemos analisar que, ao tentar inserir um registro (linha 74) é retornado dentro do DTO uma lista de possíveis erros (variável item).
Caso a operação de InsertAsync retorne algo, sera retornado o Http Status Code 422 (linha 79) com todas as msgs de validação de negócio (validação semântica)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m5lxutvvn8y1e3p9991x.png)

Veja a execução e o retorno:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6a5ryid0erbum1kwctp0.png)

Então ao enviar um request com:
- Nome em branco
- Peso igual a zero.

Vamos obter o resultado da validação de semântica e o Http Status Code 422.

Plus sobre o artigo ...

Neste artigo não vou explicar como estamos construindo as validações, mas vou deixar um print aos curiosos.
Quem quiser, pode entrar em contato que posso explicar com mais profundidade:


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8knqco05dhh7iceus9qv.png)


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gwx3oxi3dj8y616s8dm9.png)


Conclusão:

Erros semânticos nos dados fornecidos são uma parte inevitável do desenvolvimento de APIs, mas são cruciais para garantir a integridade e a consistência dos sistemas. Ao compreender e tratar adequadamente esses erros, os desenvolvedores podem construir APIs mais robustas e confiáveis, proporcionando uma melhor experiência para os usuários e garantindo o funcionamento correto das aplicações.

Link úteis:

- https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422
- https://www.rfc-editor.org/rfc/rfc4918