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)
Veja a execução e o retorno:
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:
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
